ci: add upgrade tests

2026-01-26 14:13:13 +01:00
506 changed files with 16657 additions and 58157 deletions
@@ -2,7 +2,7 @@
 # Copy this file to .env and fill in your values

 # LLM Configuration (Required)
-# Supported providers: openai, groq, ollama, gemini, anthropic, lmstudio, vertexai
+# Supported providers: openai, groq, ollama, gemini, anthropic, lmstudio
 HINDSIGHT_API_LLM_PROVIDER=openai
 HINDSIGHT_API_LLM_API_KEY=your-api-key-here
 HINDSIGHT_API_LLM_MODEL=o3-mini
@@ -13,13 +13,6 @@ HINDSIGHT_API_LLM_BASE_URL=https://api.openai.com/v1
 # HINDSIGHT_API_LLM_API_KEY=your-anthropic-api-key
 # HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-20250514

-# Example: Google Vertex AI configuration
-# HINDSIGHT_API_LLM_PROVIDER=vertexai
-# HINDSIGHT_API_LLM_MODEL=google/gemini-2.0-flash-001
-# HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=your-gcp-project-id
-# HINDSIGHT_API_LLM_VERTEXAI_REGION=us-central1
-# HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/path/to/service-account-key.json  # Optional, uses ADC if not set
-
 # Example: LM Studio local configuration (Qwen 2.5 32B recommended)
 # HINDSIGHT_API_LLM_PROVIDER=lmstudio
 # HINDSIGHT_API_LLM_API_KEY=lmstudio
@@ -33,7 +26,6 @@ HINDSIGHT_API_LOG_LEVEL=info

 # Database (Optional - uses embedded pg0 by default)
 # HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/db
-# HINDSIGHT_API_DATABASE_SCHEMA=public  # PostgreSQL schema name (default: public)

 # Embeddings Configuration (Optional - uses local by default)
 # Provider: "local" (default) or "tei" (HuggingFace Text Embeddings Inference)
@@ -50,18 +42,3 @@ HINDSIGHT_API_LOG_LEVEL=info
 # HINDSIGHT_API_RERANKER_LOCAL_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
 # For TEI provider:
 # HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8081
-
-# Observability & Tracing (Optional - disabled by default)
-# Enable OpenTelemetry tracing for LLM calls (GenAI semantic conventions)
-# HINDSIGHT_API_OTEL_TRACES_ENABLED=true
-#
-# Local development with Grafana LGTM stack (recommended - see scripts/dev/grafana/README.md)
-# HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-#
-# Cloud backends (Grafana Cloud, Langfuse, DataDog, etc.)
-# HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend-url
-# HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
-#
-# Custom service name and environment (optional, defaults: hindsight-api, development)
-# HINDSIGHT_API_OTEL_SERVICE_NAME=hindsight-production
-# HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT=production
@@ -139,104 +139,6 @@ jobs:
        path: hindsight-clients/typescript/*.tgz
        retention-days: 1

-  release-openclaw-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/openclaw
-      run: npm ci
-
-    - name: Build
-      working-directory: ./hindsight-integrations/openclaw
-      run: npm run build
-
-    - name: Publish to npm
-      working-directory: ./hindsight-integrations/openclaw
-      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/openclaw
-      run: npm pack
-
-    - name: Upload artifacts
-      uses: actions/upload-artifact@v4
-      with:
-        name: openclaw-integration
-        path: hindsight-integrations/openclaw/*.tgz
-        retention-days: 1
-
-  release-ai-sdk-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/ai-sdk
-      run: npm ci
-
-    - name: Build
-      working-directory: ./hindsight-integrations/ai-sdk
-      run: npm run build
-
-    - name: Publish to npm
-      working-directory: ./hindsight-integrations/ai-sdk
-      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/ai-sdk
-      run: npm pack
-
-    - name: Upload artifacts
-      uses: actions/upload-artifact@v4
-      with:
-        name: ai-sdk-integration
-        path: hindsight-integrations/ai-sdk/*.tgz
-        retention-days: 1
-
  release-control-plane:
    runs-on: ubuntu-latest
    environment: npm
@@ -340,7 +242,6 @@ jobs:
        retention-days: 1

  release-docker-images:
-    name: Release Docker (${{ matrix.image_name }}${{ matrix.tag_suffix }})
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -350,28 +251,10 @@ jobs:
        include:
          - target: api-only
            image_name: hindsight-api
-            tag_suffix: ""
-            build_args: ""
-          - target: api-only
-            image_name: hindsight-api
-            tag_suffix: "-slim"
-            build_args: |
-              INCLUDE_LOCAL_MODELS=false
-              PRELOAD_ML_MODELS=false
          - target: cp-only
            image_name: hindsight-control-plane
-            tag_suffix: ""
-            build_args: ""
          - target: standalone
            image_name: hindsight
-            tag_suffix: ""
-            build_args: ""
-          - target: standalone
-            image_name: hindsight
-            tag_suffix: "-slim"
-            build_args: |
-              INCLUDE_LOCAL_MODELS=false
-              PRELOAD_ML_MODELS=false

    steps:
    - uses: actions/checkout@v4
@@ -409,9 +292,6 @@ jobs:
      uses: docker/metadata-action@v5
      with:
        images: ghcr.io/${{ github.repository_owner }}/${{ matrix.image_name }}
-        flavor: |
-          latest=auto
-          suffix=${{ matrix.tag_suffix }}
        tags: |
          type=semver,pattern={{version}},value=${{ steps.get_version.outputs.VERSION }}
          type=semver,pattern={{major}}.{{minor}},value=${{ steps.get_version.outputs.VERSION }}
@@ -437,7 +317,7 @@ jobs:
    # - name: Smoke test - verify container starts
    #   env:
    #     GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
-    #   run: ./docker/test-image.sh "${{ matrix.image_name }}:test" "${{ matrix.target }}"
+    #   run: ./scripts/docker-smoke-test.sh "${{ matrix.image_name }}:test" "${{ matrix.target }}"

    # Build multi-platform and push to release tags
    - name: Build and push release images
@@ -446,7 +326,6 @@ jobs:
        context: .
        file: docker/standalone/Dockerfile
        target: ${{ matrix.target }}
-        build-args: ${{ matrix.build_args }}
        push: true
        platforms: linux/amd64,linux/arm64
        tags: ${{ steps.meta.outputs.tags }}
@@ -487,7 +366,7 @@ jobs:

  create-github-release:
    runs-on: ubuntu-latest
-    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]
+    needs: [release-python-packages, release-typescript-client, release-control-plane, release-rust-cli, release-docker-images, release-helm-chart]
    permissions:
      contents: write

@@ -510,18 +389,6 @@ jobs:
        name: typescript-client
        path: ./artifacts/typescript-client

-    - name: Download OpenClaw Integration
-      uses: actions/download-artifact@v4
-      with:
-        name: openclaw-integration
-        path: ./artifacts/openclaw-integration
-
-    - name: Download AI SDK Integration
-      uses: actions/download-artifact@v4
-      with:
-        name: ai-sdk-integration
-        path: ./artifacts/ai-sdk-integration
-
    - name: Download Control Plane
      uses: actions/download-artifact@v4
      with:
@@ -563,10 +430,6 @@ jobs:
        cp artifacts/python-packages/hindsight-embed/dist/* release-assets/ || true
        # TypeScript client
        cp artifacts/typescript-client/*.tgz release-assets/ || true
-        # OpenClaw Integration
-        cp artifacts/openclaw-integration/*.tgz release-assets/ || true
-        # AI SDK Integration
-        cp artifacts/ai-sdk-integration/*.tgz release-assets/ || true
        # Control Plane
        cp artifacts/control-plane/*.tgz release-assets/ || true
        # Rust CLI binaries
@@ -9,11 +9,42 @@ concurrency:
  cancel-in-progress: true

 jobs:
+  build-python-packages:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - name: hindsight-all
+            path: hindsight
+          - name: hindsight-api
+            path: hindsight-api
+          - name: hindsight-client
+            path: hindsight-clients/python
+          - name: hindsight-embed
+            path: hindsight-embed
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Build ${{ matrix.name }}
+      working-directory: ./${{ matrix.path }}
+      run: uv build
+
  build-api-python-versions:
    runs-on: ubuntu-latest
    strategy:
      matrix:
-        python-version: ['3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13']

    steps:
    - uses: actions/checkout@v4
@@ -51,52 +82,6 @@ jobs:
    - name: Build TypeScript client
      run: npm run build --workspace=hindsight-clients/typescript

-  build-openclaw-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/openclaw
-      run: npm ci
-
-    - name: Run tests
-      working-directory: ./hindsight-integrations/openclaw
-      run: npm test
-
-    - name: Build
-      working-directory: ./hindsight-integrations/openclaw
-      run: npm run build
-
-  build-ai-sdk-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/ai-sdk
-      run: npm ci
-
-    - name: Run tests
-      working-directory: ./hindsight-integrations/ai-sdk
-      run: npm test
-
-    - name: Build
-      working-directory: ./hindsight-integrations/ai-sdk
-      run: npm run build
-
  build-control-plane:
    runs-on: ubuntu-latest

@@ -277,35 +262,16 @@ jobs:
      run: helm lint helm/hindsight

  build-docker-images:
-    name: Build Docker (${{ matrix.name }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - target: api-only
            name: api
-            variant: full
-            build_args: ""
-          - target: api-only
-            name: api-slim
-            variant: slim
-            build_args: |
-              INCLUDE_LOCAL_MODELS=false
-              PRELOAD_ML_MODELS=false
          - target: cp-only
            name: control-plane
-            variant: full
-            build_args: ""
          - target: standalone
            name: standalone
-            variant: full
-            build_args: ""
-          - target: standalone
-            name: standalone-slim
-            variant: slim
-            build_args: |
-              INCLUDE_LOCAL_MODELS=false
-              PRELOAD_ML_MODELS=false

    steps:
    - uses: actions/checkout@v4
@@ -324,31 +290,20 @@ jobs:
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3

-    - name: Build ${{ matrix.name }} image (${{ matrix.variant }})
+    - name: Build ${{ matrix.name }} image
      uses: docker/build-push-action@v6
      with:
        context: .
        file: docker/standalone/Dockerfile
        target: ${{ matrix.target }}
-        build-args: ${{ matrix.build_args }}
        push: false
-        load: ${{ matrix.variant == 'slim' }}
-        tags: hindsight-${{ matrix.name }}:test
-        # Removed GitHub Actions cache (type=gha) - it frequently returns 502 errors
-        # causing buildx to fail with "failed to parse error response 502"
-        # Build will be slower but more reliable
+        load: false

-    # Only test slim variants to save disk space (they're much smaller)
-    # Slim variants require external embedding providers
-    - name: Smoke test - verify container starts
-      if: matrix.variant == 'slim'
-      env:
-        GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
-        HINDSIGHT_API_EMBEDDINGS_PROVIDER: openai
-        HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-        HINDSIGHT_API_RERANKER_PROVIDER: cohere
-        HINDSIGHT_API_COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
-      run: ./docker/test-image.sh "hindsight-${{ matrix.name }}:test" "${{ matrix.target }}"
+    # TODO: Re-enable smoke test when disk space issue is resolved
+    # - name: Smoke test - verify container starts
+    #   env:
+    #     GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+    #   run: ./scripts/docker-smoke-test.sh "hindsight-${{ matrix.name }}:test" "${{ matrix.target }}"

  test-api:
    runs-on: ubuntu-latest
@@ -771,9 +726,9 @@ jobs:
  test-embed:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_EMBED_LLM_PROVIDER: groq
+      HINDSIGHT_EMBED_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_EMBED_LLM_MODEL: openai/gpt-oss-20b
      # Prefer CPU-only PyTorch in CI
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

@@ -804,62 +759,10 @@ jobs:
          ${{ runner.os }}-huggingface-embed-
          ${{ runner.os }}-huggingface-

-    - name: Run unit and integration tests
-      working-directory: ./hindsight-embed
-      run: uv run pytest tests/ -v
-
    - name: Run smoke test
      working-directory: ./hindsight-embed
      run: ./test.sh

-  test-hindsight-all:
-    runs-on: ubuntu-latest
-    env:
-      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: 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: 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 hindsight-all
-      working-directory: ./hindsight
-      run: uv build
-
-    - name: Install dependencies
-      working-directory: ./hindsight
-      run: uv sync --frozen --extra test --index-strategy unsafe-best-match
-
-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-all-${{ hashFiles('hindsight/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-all-
-          ${{ runner.os }}-huggingface-
-
-    - name: Run unit tests
-      working-directory: ./hindsight
-      run: uv run pytest tests/ -v
-
  test-doc-examples:
    runs-on: ubuntu-latest
    needs: test-rust-cli
@@ -1032,18 +935,6 @@ jobs:
      working-directory: ./hindsight-dev
      run: uv run pytest upgrade_tests/ -v --tb=short

-    - name: Show upgrade test logs
-      if: always()
-      run: |
-        echo "=== Upgrade Test Server Logs ==="
-        for log in /tmp/upgrade-test-*.log; do
-          if [ -f "$log" ]; then
-            echo ""
-            echo "--- $log ---"
-            tail -500 "$log"
-          fi
-        done
-
  verify-generated-files:
    runs-on: ubuntu-latest
    env:
@@ -1114,52 +1005,4 @@ jobs:
          git diff --stat
          exit 1
        fi
-        echo "✓ All generated files are up to date"
-
-  check-openapi-compatibility:
-    runs-on: ubuntu-latest
-    env:
-      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0  # Fetch full git history to access base branch
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Install hindsight-dev dependencies
-      run: |
-        cd hindsight-dev && uv sync --frozen --index-strategy unsafe-best-match
-
-    - name: Check OpenAPI compatibility with base branch
-      run: |
-        # Get the base branch (usually main)
-        BASE_BRANCH="${{ github.base_ref }}"
-
-        if [ -z "$BASE_BRANCH" ]; then
-          echo "⚠️  Warning: No base branch found (not a PR?). Skipping compatibility check."
-          exit 0
-        fi
-
-        echo "Checking OpenAPI compatibility against base branch: $BASE_BRANCH"
-
-        # Extract the old OpenAPI spec from base branch
-        git show "origin/$BASE_BRANCH:hindsight-docs/static/openapi.json" > /tmp/old-openapi.json
-
-        if [ ! -s /tmp/old-openapi.json ]; then
-          echo "⚠️  Warning: Could not find OpenAPI spec in base branch. Skipping compatibility check."
-          exit 0
-        fi
-
-        # Check compatibility using our tool
-        cd hindsight-dev
-        uv run check-openapi-compatibility /tmp/old-openapi.json ../hindsight-docs/static/openapi.json
+        echo "✓ All generated files are up to date"
@@ -45,12 +45,9 @@ hindsight-docs/static/llms-full.txt

 hindsight-dev/benchmarks/locomo/results/
 hindsight-dev/benchmarks/longmemeval/results/
-hindsight-dev/benchmarks/consolidation/results/
-benchmarks/results/
 hindsight-cli/target
 hindsight-clients/rust/target
 .claude
 whats-next.md
 TASK.md
-# Changelog is now tracked in hindsight-docs/src/pages/changelog.md
-# CHANGELOG.md
+CHANGELOG.md
@@ -7,7 +7,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 Hindsight is an agent memory system that provides long-term memory for AI agents using biomimetic data structures. Memories are organized as:
 - **World facts**: General knowledge ("The sky is blue")
 - **Experience facts**: Personal experiences ("I visited Paris in 2023")
- **Mental models**: Consolidated knowledge synthesized from facts ("User prefers functional programming patterns")
+- **Opinion facts**: Beliefs with confidence scores ("Paris is beautiful" - 0.9 confidence)
+- **Observations**: Complex mental models derived from reflection

 ## Development Commands

@@ -45,7 +46,6 @@ cd hindsight-control-plane && npm run dev
 ./scripts/dev/start-docs.sh
 ```

-
 ### Generating Clients/OpenAPI
 ```bash
 # Regenerate OpenAPI spec after API changes (REQUIRED after changing endpoints)
@@ -101,7 +101,7 @@ cd hindsight-control-plane && npm run dev
 Main operations:
 - **Retain**: Store memories, extracts facts/entities/relationships
 - **Recall**: Retrieve memories via 4 parallel strategies (semantic, BM25, graph, temporal) + reranking
- **Reflect**: Disposition-aware reasoning using memories and mental models.
+- **Reflect**: Deep analysis forming new opinions/observations (disposition-aware)

 ### Database
 PostgreSQL with pgvector. Schema managed via Alembic migrations in `hindsight-api/hindsight_api/alembic/`. Migrations run automatically on API startup.
@@ -93,34 +93,6 @@ uv run ty check hindsight_api  # Type check
 3. Run tests to ensure nothing breaks
 4. Submit a PR with a clear description of changes

-## Release Process
-
-The project uses `scripts/release.sh` for creating releases. This script automates the entire release workflow:
-
-1. Bumps version in all components (API, clients, CLI, control plane, Helm)
-2. **Regenerates OpenAPI spec and client SDKs** (Python, TypeScript, Rust)
-3. Updates documentation versioning
-4. Creates a commit and git tag
-5. Pushes to GitHub (triggers CI/CD to publish packages)
-
-### Usage
-
-```bash
-./scripts/release.sh <version>
-```
-
-**Example:**
-```bash
-./scripts/release.sh 0.5.0
-```
-
-### Important for Developers
-
- During development, version bumps in `__init__.py` do NOT require client regeneration
- Clients are only regenerated during releases
- Do not manually run `./scripts/generate-clients.sh` unless testing generation changes
- Client version comments will reflect the API version from the latest release
-
 ## Reporting Issues

 Open an issue on GitHub with:
@@ -1,6 +1,6 @@
 <div align="center">

-![Hindsight Banner](./hindsight-docs/static/img/hindsight-github-banner.png)
+![Hindsight Banner](./hindsight-docs/static/img/banner.svg)

 [Documentation](https://hindsight.vectorize.io) • [Paper](https://arxiv.org/abs/2512.12818) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Hindsight Cloud](https://vectorize.io/hindsight/cloud)

@@ -17,66 +17,76 @@

 ## What is Hindsight?

-Hindsight™ is an agent memory system built to create smarter agents that learn over time. Most agent memory systems focus on recalling conversation history. Hindsight is focused on making agents that learn, not just remember.
+Hindsight™ is an agent memory system built to create smarter agents that learn over time. It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks.

+Hindsight addresses common challenges that have frustrated AI engineers building agents to automate tasks and assist users with conversational interfaces. Many of these challenges stem directly from a lack of memory.

-<video src="https://github.com/user-attachments/assets/923b798d-3581-4897-bb62-9cfa5a931682" controls></video>
+- **Inconsistency:** Agents complete tasks successfully one time, then fail when asked to complete the same task again. Memory gives the agent a mechanism to remember what worked and what didn't and to use that information to reduce errors and improve consistency.
+- **Hallucinations:** Long term memory can be seeded with external knowledge to ground agent behavior in reliable sources to augment training data.
+- **Cognitive Overload:** As workflows get complex, retrievals, tool calls, user messages and agent responses can grow to fill the context window leading to context rot. Short term memory optimization allows agents to reduce tokens and focus context by removing irrelevant details.

-It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks.
+## How is Hindsight Different From Other Memory Systems?
+
+![Overview](./hindsight-docs/static/img/hindsight-overview.webp)
+
+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")
+- **Opinion:** Beliefs with confidence scores ("I shouldn't touch the stove again" - .99 confidence)
+- **Observation:** Complex mental models derived by reflecting on facts and experiences ("Curling irons, ovens, and fire are also hot. I shouldn't touch those either.")
+
+Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
+
+Hindsight provides three simple methods to interact with the system:
+
+- **Retain:** Provide information to Hindsight that you want it to remember
+- **Recall:** Retrieve memories from Hindsight
+- **Reflect:** Reflect on memories and experiences to generate new observations and insights from existing memories.
+
+### Agent Memory That Learns
+
+A key goal of Hindsight is to build agent memory that enables agents to learn and improve over time. This is the role of the `reflect` operation which provides the agent to form broader opinions and observations over time.
+
+For example, imagine a product support agent that is helping a user troubleshoot a problem. It uses a `search-documentation` tool it found on an MCP server. Later in the conversation, the agent discovers that the documentation returned from the tool wasn't for the product the user was asking about. The agent now has an experience in its memory bank. And just like humans, we want that agent to learn from its experience.
+
+As the agent gains more experiences, `reflect` allows the agent to form observations about what worked, what didn't, and what to do differently the next time it encounters a similar task.
+
+---

 ## Memory Performance & Accuracy

-Hindsight is the most accurate agent memory system ever tested according to benchmark performance. It has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of January 2026 is shown here:
+Hindsight has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational
+AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of December 2025 is shown here:

 ![Overview](./hindsight-docs/static/img/hindsight-bench.jpg)

-The benchmark performance data for Hindsight has been independently reproduced by research collaborators at the Virginia Tech [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors.
+The benchmark performance data for Hindsight and GPT-4o (full context) have been reproduced by research collaborators at the Virginia Tech [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors.

-Hindsight is being used in production at Fortune 500 enterprises and by a growing number of AI startups. 
-
-## Adding Hindsight to Your AI Agents
-
-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.
-
-![Hindsight Banner](./hindsight-docs/static/img/migration-code.png)
+A thorough examination of the techniques implemented in Hindsight and detailed breakdowns of benchmark performance are [available on arXiv](https://arxiv.org/abs/2512.12818). This research is currently being prepared for conference submission and the wider peer review process.

+The benchmark results from this research can be inspected in our [visual benchmark explorer](https://hindsight-benchmarks.vercel.app). As additional improvements are made to Hindsight, new benchmark data will be available for review using this same tool.

 ## Quick Start

 ### Docker (recommended)

 ```bash
-export OPENAI_API_KEY=sk-xxx
+export OPENAI_API_KEY=your-key

 docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  -e HINDSIGHT_API_LLM_MODEL=o3-mini \
  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest
 ```

->API: http://localhost:8888
->UI: http://localhost:9999
-
 You can modify the LLM provider by setting `HINDSIGHT_API_LLM_PROVIDER`. Valid options are `openai`, `anthropic`, `gemini`, `groq`, `ollama`, and `lmstudio`. The documentation provides more details on [supported models](https://hindsight.vectorize.io/developer/models).

+API: http://localhost:8888  
+UI: http://localhost:9999

-
-### Docker (external PostgreSQL)
-
-```bash
-export OPENAI_API_KEY=sk-xxx
-export HINDSIGHT_DB_PASSWORD=choose-a-password
-cd docker/docker-compose
-docker compose up 
-```
-
-
->API: http://localhost:8888
->UI: http://localhost:9999
-
-### Client
+Install client:

 ```bash
 pip install hindsight-client -U
@@ -84,7 +94,7 @@ pip install hindsight-client -U
 npm install @vectorize-io/hindsight-client
 ```

-#### Python
+Python example:

 ```python
 from hindsight_client import Hindsight
@@ -101,29 +111,7 @@ client.recall(bank_id="my-bank", query="What does Alice do?")
 client.reflect(bank_id="my-bank", query="Tell me about Alice")
 ```

-#### Node.js / TypeScript
-
-```bash
-npm install @vectorize-io/hindsight-client
-```
-
-```javascript
-const { HindsightClient } = require('@vectorize-io/hindsight-client');
-
-const main = async () => {
-  const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
-
-  await client.retain('my-bank', 'Alice loves hiking in Yosemite');
-
-  const results = await client.recall('my-bank', 'What does Alice like?');
-  console.log(results);
-}
-
-main();
-```
-
-
-### Python Embedded (no server required)
+### Python (embedded, no Docker)

 ```bash
 pip install hindsight-all -U
@@ -143,48 +131,25 @@ with HindsightServer(
    results = client.recall(bank_id="my-bank", query="Where does Alice work?")
 ```

+### Node.js / TypeScript

---
+```bash
+npm install @vectorize-io/hindsight-client
+```

-## Use Cases
+```javascript
+const { HindsightClient } = require('@vectorize-io/hindsight-client');

+const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });

-Hindsight is built to support conversational AI agents as well as agents that are intended to perform tasks autonomously. The ideal use case for Hindsight are agents that require a blend of these features such as AI employees that need to handle open-ended tasks, change behavior based on user feedback, and learn to perform complex tasks to automate work at a level that approximates a human work. Hindsight can be used with simple AI workflows like those built with n8n and other similar tools, but may be overkill for such applications.
-
-### Per-User Memories and Chat History
-
-One of the simpler use cases you can use Hindsight for is to personalize AI chatbots and other conversational agents by storing and recalling memories associated with individual users.
-
-The requirements for this use case usually look something like this:
-
-![Per-User Memories](./hindsight-docs/static/img/per-user-memory-requirements.png)
-
-<video src="https://github.com/user-attachments/assets/4805e8e1-e7d1-47c6-a4f8-2344a5ec8906" controls></video>
-
-Satisfying these requirements in Hindsight is straightforward. When new user inputs and tool calls are ingested into Hindsight using the retain operation, custom metadata can be used to enrich the new memories. Metadata provides a convenient way to isolate memories that need to be restricted to a given user. Once these are fed into the retain operation, any raw memories and mental models that get created can be filtered when retrieving relevant memories. 
-
-![Per-User Memories](./hindsight-docs/static/img/per-user-memory-howto.png)
+await client.retain('my-bank', 'Alice loves hiking in Yosemite');
+await client.recall('my-bank', 'What does Alice like?');
+```

 ---

 ## Architecture & Operations

-![Overview](./hindsight-docs/static/img/hindsight-overview.webp)
-
-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")
- **Mental Models:** Learned understanding of the agent's world formed by reflecting on raw memories and experiences.
-
-Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
-
-Hindsight provides three simple methods to interact with the system:
-
- **Retain:** Provide information to Hindsight that you want it to remember
- **Recall:** Retrieve memories from Hindsight
- **Reflect:** Reflect on memories and experiences to generate new observations and insights from existing memories.
-
 ### Retain

 The `retain` operation is used to push new memories into Hindsight. It tells Hindsight to _retain_ the information you pass in as an input.
@@ -243,7 +208,7 @@ The final output is trimmed as needed to fit within the token limit.

 ### Reflect

-The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories and build a more thorough understanding of its world.
+The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories which are then persisted as opinions and/or observations. When building agents, the reflect operation is a key capability to enable the agent to learn from its experiences. 

 For example, the `reflect` operation can be used to support use cases such as:

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

 # Pre-download ML models to avoid runtime download (conditional)
 # Only runs if both PRELOAD_ML_MODELS=true AND INCLUDE_LOCAL_MODELS=true
-# Includes retry logic with exponential backoff for transient network failures
 ARG PRELOAD_ML_MODELS
 ARG INCLUDE_LOCAL_MODELS
-ENV HF_HUB_DOWNLOAD_TIMEOUT=600
 RUN if [ "$PRELOAD_ML_MODELS" = "true" ] && [ "$INCLUDE_LOCAL_MODELS" = "true" ]; then \
-    MAX_RETRIES=3; \
-    RETRY_DELAY=10; \
-    for i in $(seq 1 $MAX_RETRIES); do \
-      echo "Attempt $i/$MAX_RETRIES: Downloading ML models..."; \
-      /app/api/.venv/bin/python -c "\
-import os; os.environ['HF_HUB_DOWNLOAD_TIMEOUT'] = '600'; \
+    /app/api/.venv/bin/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('Downloading tiktoken encoding...'); import tiktoken; tiktoken.get_encoding('cl100k_base'); \
-print('Models cached successfully')" && break; \
-      if [ $i -lt $MAX_RETRIES ]; then \
-        echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."; \
-        sleep $RETRY_DELAY; \
-        RETRY_DELAY=$((RETRY_DELAY * 2)); \
-      fi; \
-    done; \
-    if [ $i -eq $MAX_RETRIES ] && ! /app/api/.venv/bin/python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-en-v1.5')" 2>/dev/null; then \
-      echo "ERROR: Failed to download models after $MAX_RETRIES attempts"; \
-      exit 1; \
-    fi; \
+print('Models cached successfully')"; \
    elif [ "$INCLUDE_LOCAL_MODELS" != "true" ]; then echo "Skipping ML model preload (local-models not included)"; \
    else echo "Skipping ML model preload"; fi

@@ -208,10 +190,6 @@ ENV HINDSIGHT_API_LOG_LEVEL=info
 ENV HINDSIGHT_ENABLE_API=true
 ENV HINDSIGHT_ENABLE_CP=false
 ENV PYTHONUNBUFFERED=1
-# Suppress verbose transformers/HuggingFace model loading warnings
-ENV TRANSFORMERS_VERBOSITY=error
-ENV HF_HUB_VERBOSITY=error
-ENV TOKENIZERS_PARALLELISM=false

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

@@ -299,34 +277,16 @@ ENV PATH="/app/api/.venv/bin:${PATH}"

 # Pre-download ML models to avoid runtime download (conditional)
 # Only runs if both PRELOAD_ML_MODELS=true AND INCLUDE_LOCAL_MODELS=true
-# Includes retry logic with exponential backoff for transient network failures
 ARG PRELOAD_ML_MODELS
 ARG INCLUDE_LOCAL_MODELS
-ENV HF_HUB_DOWNLOAD_TIMEOUT=600
 RUN if [ "$PRELOAD_ML_MODELS" = "true" ] && [ "$INCLUDE_LOCAL_MODELS" = "true" ]; then \
-    MAX_RETRIES=3; \
-    RETRY_DELAY=10; \
-    for i in $(seq 1 $MAX_RETRIES); do \
-      echo "Attempt $i/$MAX_RETRIES: Downloading ML models..."; \
-      /app/api/.venv/bin/python -c "\
-import os; os.environ['HF_HUB_DOWNLOAD_TIMEOUT'] = '600'; \
+    /app/api/.venv/bin/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('Downloading tiktoken encoding...'); import tiktoken; tiktoken.get_encoding('cl100k_base'); \
-print('Models cached successfully')" && break; \
-      if [ $i -lt $MAX_RETRIES ]; then \
-        echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."; \
-        sleep $RETRY_DELAY; \
-        RETRY_DELAY=$((RETRY_DELAY * 2)); \
-      fi; \
-    done; \
-    if [ $i -eq $MAX_RETRIES ] && ! /app/api/.venv/bin/python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-en-v1.5')" 2>/dev/null; then \
-      echo "ERROR: Failed to download models after $MAX_RETRIES attempts"; \
-      exit 1; \
-    fi; \
+print('Models cached successfully')"; \
    elif [ "$INCLUDE_LOCAL_MODELS" != "true" ]; then echo "Skipping ML model preload (local-models not included)"; \
    else echo "Skipping ML model preload"; fi

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

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

@@ -1,51 +0,0 @@
-#!/bin/bash
-#
-# Local Test Script for Slim Docker Images
-#
-# This script makes it easy to test slim images locally with external providers.
-# It expects API keys to be set in environment variables.
-#
-# Usage:
-#   export GROQ_API_KEY=gsk_xxx
-#   export OPENAI_API_KEY=sk-xxx
-#   export COHERE_API_KEY=xxx
-#   ./docker/test-slim-local.sh
-#
-# Or inline:
-#   GROQ_API_KEY=gsk_xxx OPENAI_API_KEY=sk_xxx COHERE_API_KEY=xxx ./docker/test-slim-local.sh
-#
-
-set -euo pipefail
-
-# Check for required API keys
-if [ -z "${GROQ_API_KEY:-}" ]; then
-    echo "❌ Error: GROQ_API_KEY environment variable is required"
-    echo "Set it with: export GROQ_API_KEY=gsk_xxx"
-    exit 1
-fi
-
-if [ -z "${OPENAI_API_KEY:-}" ]; then
-    echo "❌ Error: OPENAI_API_KEY environment variable is required"
-    echo "Set it with: export OPENAI_API_KEY=sk-xxx"
-    exit 1
-fi
-
-if [ -z "${COHERE_API_KEY:-}" ]; then
-    echo "❌ Error: COHERE_API_KEY environment variable is required"
-    echo "Set it with: export COHERE_API_KEY=xxx"
-    exit 1
-fi
-
-# Configuration
-IMAGE="${1:-hindsight-slim:test}"
-echo "Testing image: $IMAGE"
-echo ""
-
-# Set up external providers
-export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
-export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=$OPENAI_API_KEY
-export HINDSIGHT_API_RERANKER_PROVIDER=cohere
-export HINDSIGHT_API_COHERE_API_KEY=$COHERE_API_KEY
-
-# Run the test
-exec "$(dirname "$0")/test-image.sh" "$IMAGE" standalone
@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.10
-appVersion: "0.4.10"
+version: 0.3.0
+appVersion: "0.3.0"
 keywords:
  - ai
  - memory
@@ -33,7 +33,7 @@ spec:
      - name: api
        securityContext:
          {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.api.image.repository }}:{{ .Values.api.image.tag | default .Values.version | default .Chart.AppVersion }}"
+        image: "{{ .Values.api.image.repository }}:{{ .Values.api.image.tag | default .Values.version }}"
        imagePullPolicy: {{ .Values.api.image.pullPolicy }}
        ports:
        - name: http
@@ -60,9 +60,6 @@ spec:
        - name: HINDSIGHT_API_WORKER_ENABLED
          value: "false"
        {{- end }}
-        {{- /* Explicitly set port to override K8s service discovery env var (HINDSIGHT_API_PORT) */}}
-        - name: HINDSIGHT_API_PORT
-          value: {{ .Values.api.service.targetPort | quote }}
        {{- range $key, $value := .Values.api.env }}
        - name: {{ $key }}
          value: {{ $value | quote }}
@@ -87,7 +84,7 @@ spec:
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
-      {{- with (.Values.api.affinity | default .Values.affinity) }}
+      {{- with .Values.affinity }}
      affinity:
        {{- toYaml . | nindent 8 }}
      {{- end }}
@@ -33,7 +33,7 @@ spec:
      - name: control-plane
        securityContext:
          {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.controlPlane.image.repository }}:{{ .Values.controlPlane.image.tag | default .Values.version | default .Chart.AppVersion }}"
+        image: "{{ .Values.controlPlane.image.repository }}:{{ .Values.controlPlane.image.tag | default .Values.version }}"
        imagePullPolicy: {{ .Values.controlPlane.image.pullPolicy }}
        ports:
        - name: http
@@ -71,7 +71,7 @@ spec:
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
-      {{- with (.Values.controlPlane.affinity | default .Values.affinity) }}
+      {{- with .Values.affinity }}
      affinity:
        {{- toYaml . | nindent 8 }}
      {{- end }}
@@ -1,56 +0,0 @@
-{{- if and .Values.api.enabled .Values.api.podDisruptionBudget.enabled }}
-apiVersion: policy/v1
-kind: PodDisruptionBudget
-metadata:
-  name: {{ include "hindsight.fullname" . }}-api
-  labels:
-    {{- include "hindsight.api.labels" . | nindent 4 }}
-spec:
-  {{- if .Values.api.podDisruptionBudget.minAvailable }}
-  minAvailable: {{ .Values.api.podDisruptionBudget.minAvailable }}
-  {{- end }}
-  {{- if .Values.api.podDisruptionBudget.maxUnavailable }}
-  maxUnavailable: {{ .Values.api.podDisruptionBudget.maxUnavailable }}
-  {{- end }}
-  selector:
-    matchLabels:
-      {{- include "hindsight.api.selectorLabels" . | nindent 6 }}
-{{- end }}
---
-{{- if and .Values.controlPlane.enabled .Values.controlPlane.podDisruptionBudget.enabled }}
-apiVersion: policy/v1
-kind: PodDisruptionBudget
-metadata:
-  name: {{ include "hindsight.fullname" . }}-control-plane
-  labels:
-    {{- include "hindsight.controlPlane.labels" . | nindent 4 }}
-spec:
-  {{- if .Values.controlPlane.podDisruptionBudget.minAvailable }}
-  minAvailable: {{ .Values.controlPlane.podDisruptionBudget.minAvailable }}
-  {{- end }}
-  {{- if .Values.controlPlane.podDisruptionBudget.maxUnavailable }}
-  maxUnavailable: {{ .Values.controlPlane.podDisruptionBudget.maxUnavailable }}
-  {{- end }}
-  selector:
-    matchLabels:
-      {{- include "hindsight.controlPlane.selectorLabels" . | nindent 6 }}
-{{- end }}
---
-{{- if and .Values.worker.enabled .Values.worker.podDisruptionBudget.enabled }}
-apiVersion: policy/v1
-kind: PodDisruptionBudget
-metadata:
-  name: {{ include "hindsight.fullname" . }}-worker
-  labels:
-    {{- include "hindsight.worker.labels" . | nindent 4 }}
-spec:
-  {{- if .Values.worker.podDisruptionBudget.minAvailable }}
-  minAvailable: {{ .Values.worker.podDisruptionBudget.minAvailable }}
-  {{- end }}
-  {{- if .Values.worker.podDisruptionBudget.maxUnavailable }}
-  maxUnavailable: {{ .Values.worker.podDisruptionBudget.maxUnavailable }}
-  {{- end }}
-  selector:
-    matchLabels:
-      {{- include "hindsight.worker.selectorLabels" . | nindent 6 }}
-{{- end }}
@@ -32,7 +32,7 @@ spec:
      - name: worker
        securityContext:
          {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.worker.image.repository }}:{{ .Values.worker.image.tag | default .Values.version | default .Chart.AppVersion }}"
+        image: "{{ .Values.worker.image.repository }}:{{ .Values.worker.image.tag | default .Values.version }}"
        imagePullPolicy: {{ .Values.worker.image.pullPolicy }}
        command: ["hindsight-worker"]
        ports:
@@ -99,7 +99,7 @@ spec:
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
-      {{- with (.Values.worker.affinity | default .Values.affinity) }}
+      {{- with .Values.affinity }}
      affinity:
        {{- toYaml . | nindent 8 }}
      {{- end }}
@@ -1,8 +1,7 @@
 # Default values for hindsight

-# Global version override - use this to set a consistent image tag across all components
-# If not set, defaults to Chart.appVersion from Chart.yaml
-# version: ""
+# Chart version - use this to set a consistent image tag across all components
+version: "0.1.1"

 # Use an existing secret instead of creating one from values
 # When set, all keys from this secret are injected as environment variables via envFrom
@@ -58,15 +57,6 @@ api:
    timeoutSeconds: 3
    failureThreshold: 3

-  # Pod disruption budget
-  podDisruptionBudget:
-    enabled: false
-    minAvailable: 1
-    # maxUnavailable: 1
-
-  # Pod affinity/anti-affinity (overrides global affinity for this component)
-  # affinity: {}
-
  # Environment variables
  env:
    #HINDSIGHT_API_LLM_PROVIDER: "groq"
@@ -85,7 +75,7 @@ worker:
  image:
    repository: ghcr.io/vectorize-io/hindsight-api
    pullPolicy: IfNotPresent
-    # tag: ""  # defaults to .Values.version, then Chart.appVersion if not specified
+    # tag defaults to .Values.version if not specified

  service:
    # Service for metrics scraping (headless for StatefulSet)
@@ -131,15 +121,6 @@ worker:
    # HTTP port for metrics/health (matches service.targetPort)
    HINDSIGHT_API_WORKER_HTTP_PORT: "8889"

-  # Pod disruption budget
-  podDisruptionBudget:
-    enabled: false
-    minAvailable: 1
-    # maxUnavailable: 1
-
-  # Pod affinity/anti-affinity (overrides global affinity for this component)
-  # affinity: {}
-
  # Secret environment variables (inherited from api.secrets if not specified)
  secrets: {}

@@ -183,15 +164,6 @@ controlPlane:
    timeoutSeconds: 3
    failureThreshold: 3

-  # Pod disruption budget
-  podDisruptionBudget:
-    enabled: false
-    minAvailable: 1
-    # maxUnavailable: 1
-
-  # Pod affinity/anti-affinity (overrides global affinity for this component)
-  # affinity: {}
-
  # Environment variables
  env:
    NODE_ENV: "production"
@@ -290,7 +262,7 @@ nodeSelector: {}
 # Tolerations
 tolerations: []

-# Affinity (applied to all components unless overridden per-component)
+# Affinity
 affinity: {}

 # Autoscaling
@@ -46,4 +46,4 @@ __all__ = [
    "RemoteTEICrossEncoder",
    "LLMConfig",
 ]
-__version__ = "0.4.10"
+__version__ = "0.1.0"
@@ -11,7 +11,6 @@ from collections.abc import Sequence
 import sqlalchemy as sa
 from alembic import op
 from pgvector.sqlalchemy import Vector
-from sqlalchemy import text
 from sqlalchemy.dialects import postgresql

 # revision identifiers, used by Alembic.
@@ -24,21 +23,8 @@ depends_on: str | Sequence[str] | None = None
 def upgrade() -> None:
    """Upgrade schema - create all tables from scratch."""

-    # Note: pgvector extension is installed globally BEFORE migrations run
-    # See migrations.py:run_migrations() - this ensures the extension is available
-    # to all schemas, not just the one being migrated
-
-    # We keep this here as a fallback for backwards compatibility
-    # This may fail if user lacks permissions, which is fine if extension already exists
-    try:
-        op.execute("CREATE EXTENSION IF NOT EXISTS vector")
-    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 = 'vector'")).fetchone()
-        if not result:
-            # Extension truly doesn't exist - re-raise the error
-            raise
+    # Enable required extensions
+    op.execute("CREATE EXTENSION IF NOT EXISTS vector")

    # Create banks table
    op.create_table(
@@ -1,134 +0,0 @@
-"""Rename mental_model fact_type to observation and reflections table to mental_models
-
-Revision ID: t5o6p7q8r9s0
-Revises: s4n5o6p7q8r9
-Create Date: 2026-01-26
-
-This migration implements the terminology rename:
-1. mental_model (fact_type in memory_units) -> observation
-2. reflections table -> mental_models table
-
-The new terminology:
- Observations: Consolidated knowledge synthesized from facts (was mental_model)
- Mental Models: Stored reflect responses (was reflections)
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "t5o6p7q8r9s0"
-down_revision: str | Sequence[str] | None = "s4n5o6p7q8r9"
-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:
-    """Rename mental_model -> observation and reflections -> mental_models."""
-    schema = _get_schema_prefix()
-
-    # 1. Update fact_type values: mental_model -> observation
-    op.execute(f"""
-        UPDATE {schema}memory_units
-        SET fact_type = 'observation'
-        WHERE fact_type = 'mental_model'
-    """)
-
-    # 2. Update the CHECK constraint - remove mental_model, keep observation
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation'))
-    """)
-
-    # 3. Rename the index for observations (was for mental_models)
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_mental_models")
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_observations
-        ON {schema}memory_units(bank_id, fact_type)
-        WHERE fact_type = 'observation'
-    """)
-
-    # 4. Update the unconsolidated index to not filter by fact_type since observations
-    # are now the consolidated type
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_unconsolidated")
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_unconsolidated
-        ON {schema}memory_units (bank_id, created_at)
-        WHERE consolidated_at IS NULL AND fact_type IN ('experience', 'world')
-    """)
-
-    # 5. Rename reflections table to mental_models
-    op.execute(f"ALTER TABLE IF EXISTS {schema}reflections RENAME TO mental_models")
-
-    # 6. Rename indexes for mental_models (was reflections)
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_bank_id RENAME TO idx_mental_models_bank_id")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_embedding RENAME TO idx_mental_models_embedding")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_tags RENAME TO idx_mental_models_tags")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_text_search RENAME TO idx_mental_models_text_search")
-
-    # 7. Rename foreign key constraint
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        DROP CONSTRAINT IF EXISTS fk_reflections_bank_id
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT fk_mental_models_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-
-def downgrade() -> None:
-    """Reverse: observation -> mental_model and mental_models -> reflections."""
-    schema = _get_schema_prefix()
-
-    # 1. Rename mental_models table back to reflections
-    op.execute(f"ALTER TABLE IF EXISTS {schema}mental_models RENAME TO reflections")
-
-    # 2. Rename indexes back
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_bank_id RENAME TO idx_reflections_bank_id")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_embedding RENAME TO idx_reflections_embedding")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_tags RENAME TO idx_reflections_tags")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_text_search RENAME TO idx_reflections_text_search")
-
-    # 3. Rename foreign key back
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        DROP CONSTRAINT IF EXISTS fk_mental_models_bank_id
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        ADD CONSTRAINT fk_reflections_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # 4. Update fact_type values: observation -> mental_model
-    op.execute(f"""
-        UPDATE {schema}memory_units
-        SET fact_type = 'mental_model'
-        WHERE fact_type = 'observation'
-    """)
-
-    # 5. Update the CHECK constraint back
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation', 'mental_model'))
-    """)
-
-    # 6. Rename index back
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_observations")
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_mental_models
-        ON {schema}memory_units(bank_id, fact_type)
-        WHERE fact_type = 'mental_model'
-    """)
@@ -1,41 +0,0 @@
-"""Change mental_models.id from UUID to TEXT
-
-Revision ID: u6p7q8r9s0t1
-Revises: t5o6p7q8r9s0
-Create Date: 2026-01-27
-
-This migration changes the mental_models.id column from UUID to TEXT
-to support user-defined text identifiers like 'team-communication' instead of UUIDs.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "u6p7q8r9s0t1"
-down_revision: str | Sequence[str] | None = "t5o6p7q8r9s0"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    """Get schema prefix for table names (required for multi-tenant support)."""
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    """Change mental_models.id from UUID to TEXT."""
-    schema = _get_schema_prefix()
-
-    # Change the id column type from UUID to TEXT
-    # Existing UUIDs will be converted to their string representation
-    op.execute(f"ALTER TABLE {schema}mental_models ALTER COLUMN id TYPE TEXT USING id::TEXT")
-
-
-def downgrade() -> None:
-    """Revert mental_models.id from TEXT to UUID."""
-    schema = _get_schema_prefix()
-
-    # Note: This will fail if any id values are not valid UUIDs
-    op.execute(f"ALTER TABLE {schema}mental_models ALTER COLUMN id TYPE UUID USING id::UUID")
@@ -1,50 +0,0 @@
-"""Add max_tokens and trigger columns to mental_models
-
-Revision ID: v7q8r9s0t1u2
-Revises: u6p7q8r9s0t1
-Create Date: 2026-01-27
-
-This migration adds:
- max_tokens column: token limit for content generation during refresh
- trigger column: JSONB for trigger settings (e.g., refresh_after_consolidation)
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "v7q8r9s0t1u2"
-down_revision: str | Sequence[str] | None = "u6p7q8r9s0t1"
-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 max_tokens and trigger columns to mental_models."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD COLUMN IF NOT EXISTS max_tokens INT NOT NULL DEFAULT 2048
-    """)
-
-    # trigger column stores trigger settings as JSONB
-    # Default: refresh_after_consolidation = false (not "real time")
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD COLUMN IF NOT EXISTS trigger JSONB NOT NULL DEFAULT '{{"refresh_after_consolidation": false}}'::jsonb
-    """)
-
-
-def downgrade() -> None:
-    """Remove max_tokens and trigger columns from mental_models."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"ALTER TABLE {schema}mental_models DROP COLUMN IF EXISTS max_tokens")
-    op.execute(f"ALTER TABLE {schema}mental_models DROP COLUMN IF EXISTS trigger")
@@ -1,60 +0,0 @@
-"""Fix mental_models primary key to be scoped per bank
-
-Revision ID: w8r9s0t1u2v3
-Revises: v7q8r9s0t1u2
-Create Date: 2026-02-05
-
-This migration fixes a critical bank isolation bug where mental_models.id was
-globally unique across all banks instead of being scoped per bank. This caused
-conflicts when different banks tried to use the same custom ID.
-
-CRITICAL FIX: Changes primary key from (id) to (bank_id, id) to ensure proper isolation.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "w8r9s0t1u2v3"
-down_revision: str | Sequence[str] | None = "v7q8r9s0t1u2"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    """Get schema prefix for table names (required for multi-tenant support)."""
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    """Change mental_models primary key from (id) to (bank_id, id) for proper bank isolation."""
-    schema = _get_schema_prefix()
-
-    # Drop the old primary key constraint (just id)
-    # Note: The constraint might be named differently on different DBs
-    # Try both old names (pinned_reflections_pkey from original, mental_models_pkey from rename)
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS pinned_reflections_pkey")
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS mental_models_pkey")
-
-    # Create the new composite primary key (bank_id, id)
-    # This ensures IDs are scoped per bank, not globally
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT mental_models_pkey PRIMARY KEY (bank_id, id)
-    """)
-
-
-def downgrade() -> None:
-    """Revert mental_models primary key from (bank_id, id) to (id)."""
-    schema = _get_schema_prefix()
-
-    # Drop the composite primary key
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS mental_models_pkey")
-
-    # Restore the old primary key (just id)
-    # WARNING: This downgrade will fail if there are duplicate IDs across banks
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT mental_models_pkey PRIMARY KEY (id)
-    """)
@@ -72,24 +72,22 @@ def create_app(

    # Mount MCP server and chain its lifespan if enabled
    if mcp_app is not None:
-        # Get both MCP apps' underlying Starlette apps for lifespan access
-        multi_bank_starlette_app = mcp_app.multi_bank_app
-        single_bank_starlette_app = mcp_app.single_bank_app
+        # Get the MCP app's underlying Starlette app for lifespan access
+        mcp_starlette_app = mcp_app.mcp_app

        # Store the original lifespan
        original_lifespan = app.router.lifespan_context

        @asynccontextmanager
        async def chained_lifespan(app_instance: FastAPI):
-            """Chain both MCP lifespans with the main app lifespan."""
-            # Start both MCP lifespans (multi-bank and single-bank)
-            async with multi_bank_starlette_app.router.lifespan_context(multi_bank_starlette_app):
-                async with single_bank_starlette_app.router.lifespan_context(single_bank_starlette_app):
-                    logger.info("MCP lifespans started (multi-bank and single-bank)")
-                    # Then start the original app lifespan
-                    async with original_lifespan(app_instance):
-                        yield
-                logger.info("MCP lifespans stopped")
+            """Chain the MCP lifespan with the main app lifespan."""
+            # Start MCP lifespan first
+            async with mcp_starlette_app.router.lifespan_context(mcp_starlette_app):
+                logger.info("MCP lifespan started")
+                # Then start the original app lifespan
+                async with original_lifespan(app_instance):
+                    yield
+            logger.info("MCP lifespan stopped")

        # Replace the app's lifespan with the chained version
        app.router.lifespan_context = chained_lifespan
@@ -8,11 +8,7 @@ from contextvars import ContextVar
 from fastmcp import FastMCP

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

 # Configure logging from HINDSIGHT_API_LOG_LEVEL environment variable
 _log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
@@ -33,35 +29,21 @@ logger = logging.getLogger(__name__)
 # Default bank_id from environment variable
 DEFAULT_BANK_ID = os.environ.get("HINDSIGHT_MCP_BANK_ID", "default")

-# Legacy MCP authentication token (for backwards compatibility)
-# If set, this token is checked first before TenantExtension auth
-MCP_AUTH_TOKEN = os.environ.get("HINDSIGHT_API_MCP_AUTH_TOKEN")
-
 # Context variable to hold the current bank_id
 _current_bank_id: ContextVar[str | None] = ContextVar("current_bank_id", default=None)

-# Context variable to hold the current API key (for tenant auth propagation)
-_current_api_key: ContextVar[str | None] = ContextVar("current_api_key", default=None)
-

 def get_current_bank_id() -> str | None:
    """Get the current bank_id from context."""
    return _current_bank_id.get()


-def get_current_api_key() -> str | None:
-    """Get the current API key from context."""
-    return _current_api_key.get()
-
-
-def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
+def create_mcp_server(memory: MemoryEngine) -> FastMCP:
    """
    Create and configure the Hindsight MCP server.

    Args:
        memory: MemoryEngine instance (required)
-        multi_bank: If True, expose all tools with bank_id parameters (default).
-                   If False, only expose bank-scoped tools without bank_id parameters.

    Returns:
        Configured FastMCP server instance with stateless_http enabled
@@ -72,76 +54,36 @@ def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
    # 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
-        include_bank_id_param=multi_bank,
-        tools=None if multi_bank else {"retain", "recall", "reflect"},  # Scoped tools for single-bank mode
+        include_bank_id_param=True,  # HTTP MCP supports multi-bank via parameter
+        tools=None,  # All tools
        retain_fire_and_forget=False,  # HTTP MCP supports sync/async modes
    )

    register_mcp_tools(mcp, memory, config)

-    # Load and register additional tools from MCP extension if configured
-    mcp_extension = load_extension("MCP", MCPExtension)
-    if mcp_extension:
-        logger.info(f"Loading MCP extension: {mcp_extension.__class__.__name__}")
-        mcp_extension.register_tools(mcp, memory)
-
    return mcp


 class MCPMiddleware:
-    """ASGI middleware that handles authentication and routes to appropriate MCP server.
+    """ASGI middleware that extracts bank_id from header or path and sets context.

-    Authentication:
-        1. If HINDSIGHT_API_MCP_AUTH_TOKEN is set (legacy), validates against that token
-        2. Otherwise, uses TenantExtension.authenticate_mcp() from the MemoryEngine
-           - DefaultTenantExtension: no auth required (local dev)
-           - ApiKeyTenantExtension: validates against env var
+    Bank ID can be provided via:
+    1. X-Bank-Id header (recommended for Claude Code)
+    2. URL path: /mcp/{bank_id}/
+    3. Environment variable HINDSIGHT_MCP_BANK_ID (fallback default)

-    Two modes based on URL structure:
-
-    1. Multi-bank mode (for /mcp/ root endpoint):
-       - Exposes all tools: retain, recall, reflect, list_banks, create_bank
-       - All tools include optional bank_id parameter for cross-bank operations
-       - Bank ID from: X-Bank-Id header or HINDSIGHT_MCP_BANK_ID env var
-
-    2. Single-bank mode (for /mcp/{bank_id}/ endpoints):
-       - Exposes bank-scoped tools only: retain, recall, reflect
-       - No bank_id parameter (comes from URL)
-       - No bank management tools (list_banks, create_bank)
-       - Recommended for agent isolation
-
-    Examples:
-        # Single-bank mode (recommended for agent isolation)
-        claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/ \\
-            --header "Authorization: Bearer <token>"
-
-        # Multi-bank mode (for cross-bank operations)
+    For Claude Code, configure with:
        claude mcp add --transport http hindsight http://localhost:8888/mcp \\
-            --header "X-Bank-Id: my-bank" --header "Authorization: Bearer <token>"
+            --header "X-Bank-Id: my-bank"
    """

    def __init__(self, app, memory: MemoryEngine):
        self.app = app
        self.memory = memory
-        self.tenant_extension = memory._tenant_extension
-
-        # Create two server instances:
-        # 1. Multi-bank server (for /mcp/ root endpoint)
-        self.multi_bank_server = create_mcp_server(memory, multi_bank=True)
-        self.multi_bank_app = self.multi_bank_server.http_app(path="/")
-
-        # 2. Single-bank server (for /mcp/{bank_id}/ endpoints)
-        self.single_bank_server = create_mcp_server(memory, multi_bank=False)
-        self.single_bank_app = self.single_bank_server.http_app(path="/")
-
-        # Backward compatibility: expose multi_bank_app as mcp_app
-        self.mcp_app = self.multi_bank_app
-
-        # Expose the lifespan for the parent app to chain (use multi-bank as default)
-        self.lifespan = (
-            self.multi_bank_app.lifespan_handler if hasattr(self.multi_bank_app, "lifespan_handler") else None
-        )
+        self.mcp_server = create_mcp_server(memory)
+        self.mcp_app = self.mcp_server.http_app(path="/")
+        # Expose the lifespan for the parent app to chain
+        self.lifespan = self.mcp_app.lifespan_handler if hasattr(self.mcp_app, "lifespan_handler") else None

    def _get_header(self, scope: dict, name: str) -> str | None:
        """Extract a header value from ASGI scope."""
@@ -153,41 +95,9 @@ class MCPMiddleware:

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
-            await self.multi_bank_app(scope, receive, send)
+            await self.mcp_app(scope, receive, send)
            return

-        # Extract auth token from header (for tenant auth propagation)
-        auth_header = self._get_header(scope, "Authorization")
-        auth_token: str | None = None
-        if auth_header:
-            # Support both "Bearer <token>" and direct token
-            auth_token = auth_header[7:].strip() if auth_header.startswith("Bearer ") else auth_header.strip()
-
-        # Authenticate: check legacy MCP_AUTH_TOKEN first, then TenantExtension
-        tenant_context = None
-        if MCP_AUTH_TOKEN:
-            # Legacy authentication mode - validate against static token
-            if not auth_token:
-                await self._send_error(send, 401, "Authorization header required")
-                return
-            if auth_token != MCP_AUTH_TOKEN:
-                await self._send_error(send, 401, "Invalid authentication token")
-                return
-            # Legacy mode doesn't use tenant schemas
-            tenant_context = None
-        else:
-            # Use TenantExtension.authenticate_mcp() for auth
-            try:
-                tenant_context = await self.tenant_extension.authenticate_mcp(RequestContext(api_key=auth_token))
-            except AuthenticationError as e:
-                await self._send_error(send, 401, str(e))
-                return
-
-        # Set schema from tenant context so downstream DB queries use the correct schema
-        schema_token = (
-            _current_schema.set(tenant_context.schema_name) if tenant_context and tenant_context.schema_name else None
-        )
-
        path = scope.get("path", "")

        # Strip any mount prefix (e.g., /mcp) that FastAPI might not have stripped
@@ -201,13 +111,8 @@ class MCPMiddleware:
        elif path == "/mcp":
            path = "/"

-        # Ensure path has leading slash (needed after stripping mount path)
-        if path and not path.startswith("/"):
-            path = "/" + path
-
        # Try to get bank_id from header first (for Claude Code compatibility)
        bank_id = self._get_header(scope, "X-Bank-Id")
-        bank_id_from_path = False

        # MCP endpoint paths that should not be treated as bank_ids
        MCP_ENDPOINTS = {"sse", "messages"}
@@ -220,7 +125,6 @@ class MCPMiddleware:
            if parts[0] and parts[0] not in MCP_ENDPOINTS:
                # First segment looks like a bank_id
                bank_id = parts[0]
-                bank_id_from_path = True
                new_path = "/" + parts[1] if len(parts) > 1 else "/"

        # Fall back to default bank_id
@@ -228,15 +132,8 @@ class MCPMiddleware:
            bank_id = DEFAULT_BANK_ID
            logger.debug(f"Using default bank_id: {bank_id}")

-        # Select the appropriate MCP app based on how bank_id was provided:
-        # - Path-based bank_id → single-bank app (no bank_id param, scoped tools)
-        # - Header/env bank_id → multi-bank app (bank_id param, all tools)
-        target_app = self.single_bank_app if bank_id_from_path else self.multi_bank_app
-
-        # Set bank_id and api_key context
-        bank_id_token = _current_bank_id.set(bank_id)
-        # Store the auth token for tenant extension to validate
-        api_key_token = _current_api_key.set(auth_token) if auth_token else None
+        # Set bank_id context
+        token = _current_bank_id.set(bank_id)
        try:
            new_scope = scope.copy()
            new_scope["path"] = new_path
@@ -245,7 +142,7 @@ class MCPMiddleware:

            # Wrap send to rewrite the SSE endpoint URL to include bank_id if using path-based routing
            async def send_wrapper(message):
-                if message["type"] == "http.response.body" and bank_id_from_path:
+                if message["type"] == "http.response.body":
                    body = message.get("body", b"")
                    if body and b"/messages" in body:
                        # Rewrite /messages to /{bank_id}/messages in SSE endpoint event
@@ -253,13 +150,9 @@ class MCPMiddleware:
                        message = {**message, "body": body}
                await send(message)

-            await target_app(new_scope, receive, send_wrapper)
+            await self.mcp_app(new_scope, receive, send_wrapper)
        finally:
-            _current_bank_id.reset(bank_id_token)
-            if api_key_token is not None:
-                _current_api_key.reset(api_key_token)
-            if schema_token is not None:
-                _current_schema.reset(schema_token)
+            _current_bank_id.reset(token)

    async def _send_error(self, send, status: int, message: str):
        """Send an error response."""
@@ -281,23 +174,12 @@ class MCPMiddleware:

 def create_mcp_app(memory: MemoryEngine):
    """
-    Create an ASGI app that handles MCP requests with dynamic tool exposure.
+    Create an ASGI app that handles MCP requests.

-    Authentication:
-        Uses the TenantExtension from the MemoryEngine (same auth as REST API).
-
-    Two modes based on URL structure:
-
-    1. Single-bank mode (recommended for agent isolation):
-       - URL: /mcp/{bank_id}/
-       - Tools: retain, recall, reflect (no bank_id parameter)
-       - Example: claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/
-
-    2. Multi-bank mode (for cross-bank operations):
-       - URL: /mcp/
-       - Tools: retain, recall, reflect, list_banks, create_bank (all with bank_id parameter)
-       - Bank ID from: X-Bank-Id header or HINDSIGHT_MCP_BANK_ID env var (default: "default")
-       - Example: claude mcp add --transport http hindsight http://localhost:8888/mcp --header "X-Bank-Id: my-bank"
+    Bank ID can be provided via:
+    1. X-Bank-Id header: claude mcp add --transport http hindsight http://localhost:8888/mcp --header "X-Bank-Id: my-bank"
+    2. URL path: /mcp/{bank_id}/
+    3. Environment variable HINDSIGHT_MCP_BANK_ID (fallback, default: "default")

    Args:
        memory: MemoryEngine instance
@@ -4,8 +4,6 @@ Banner display for Hindsight API startup.
 Shows the logo and tagline with gradient colors.
 """

-from .utils import mask_network_location
-
 # Gradient colors: #0074d9 -> #009296
 GRADIENT_START = (0, 116, 217)  # #0074d9
 GRADIENT_END = (0, 146, 150)  # #009296
@@ -85,14 +83,11 @@ def print_startup_info(
    embeddings_provider: str,
    reranker_provider: str,
    mcp_enabled: bool = False,
-    version: str | None = None,
 ):
    """Print styled startup information."""
    print(color_start("Starting Hindsight API..."))
-    if version:
-        print(f"  {dim('Version:')} {color(f'v{version}', 0.1)}")
    print(f"  {dim('URL:')} {color(f'http://{host}:{port}', 0.2)}")
-    print(f"  {dim('Database:')} {color(mask_network_location(database_url), 0.4)}")
+    print(f"  {dim('Database:')} {color(database_url, 0.4)}")
    print(f"  {dim('LLM:')} {color(f'{llm_provider} / {llm_model}', 0.6)}")
    print(f"  {dim('Embeddings:')} {color(embeddings_provider, 0.8)}")
    print(f"  {dim('Reranker:')} {color(reranker_provider, 1.0)}")
@@ -20,15 +20,11 @@ logger = logging.getLogger(__name__)

 # Environment variable names
 ENV_DATABASE_URL = "HINDSIGHT_API_DATABASE_URL"
-ENV_DATABASE_SCHEMA = "HINDSIGHT_API_DATABASE_SCHEMA"
 ENV_LLM_PROVIDER = "HINDSIGHT_API_LLM_PROVIDER"
 ENV_LLM_API_KEY = "HINDSIGHT_API_LLM_API_KEY"
 ENV_LLM_MODEL = "HINDSIGHT_API_LLM_MODEL"
 ENV_LLM_BASE_URL = "HINDSIGHT_API_LLM_BASE_URL"
 ENV_LLM_MAX_CONCURRENT = "HINDSIGHT_API_LLM_MAX_CONCURRENT"
-ENV_LLM_MAX_RETRIES = "HINDSIGHT_API_LLM_MAX_RETRIES"
-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"

@@ -37,35 +33,19 @@ ENV_RETAIN_LLM_PROVIDER = "HINDSIGHT_API_RETAIN_LLM_PROVIDER"
 ENV_RETAIN_LLM_API_KEY = "HINDSIGHT_API_RETAIN_LLM_API_KEY"
 ENV_RETAIN_LLM_MODEL = "HINDSIGHT_API_RETAIN_LLM_MODEL"
 ENV_RETAIN_LLM_BASE_URL = "HINDSIGHT_API_RETAIN_LLM_BASE_URL"
-ENV_RETAIN_LLM_MAX_CONCURRENT = "HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT"
-ENV_RETAIN_LLM_MAX_RETRIES = "HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES"
-ENV_RETAIN_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF"
-ENV_RETAIN_LLM_MAX_BACKOFF = "HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF"
-ENV_RETAIN_LLM_TIMEOUT = "HINDSIGHT_API_RETAIN_LLM_TIMEOUT"

 ENV_REFLECT_LLM_PROVIDER = "HINDSIGHT_API_REFLECT_LLM_PROVIDER"
 ENV_REFLECT_LLM_API_KEY = "HINDSIGHT_API_REFLECT_LLM_API_KEY"
 ENV_REFLECT_LLM_MODEL = "HINDSIGHT_API_REFLECT_LLM_MODEL"
 ENV_REFLECT_LLM_BASE_URL = "HINDSIGHT_API_REFLECT_LLM_BASE_URL"
-ENV_REFLECT_LLM_MAX_CONCURRENT = "HINDSIGHT_API_REFLECT_LLM_MAX_CONCURRENT"
-ENV_REFLECT_LLM_MAX_RETRIES = "HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES"
-ENV_REFLECT_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF"
-ENV_REFLECT_LLM_MAX_BACKOFF = "HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF"
-ENV_REFLECT_LLM_TIMEOUT = "HINDSIGHT_API_REFLECT_LLM_TIMEOUT"

 ENV_CONSOLIDATION_LLM_PROVIDER = "HINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER"
 ENV_CONSOLIDATION_LLM_API_KEY = "HINDSIGHT_API_CONSOLIDATION_LLM_API_KEY"
 ENV_CONSOLIDATION_LLM_MODEL = "HINDSIGHT_API_CONSOLIDATION_LLM_MODEL"
 ENV_CONSOLIDATION_LLM_BASE_URL = "HINDSIGHT_API_CONSOLIDATION_LLM_BASE_URL"
-ENV_CONSOLIDATION_LLM_MAX_CONCURRENT = "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT"
-ENV_CONSOLIDATION_LLM_MAX_RETRIES = "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_RETRIES"
-ENV_CONSOLIDATION_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_CONSOLIDATION_LLM_INITIAL_BACKOFF"
-ENV_CONSOLIDATION_LLM_MAX_BACKOFF = "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_BACKOFF"
-ENV_CONSOLIDATION_LLM_TIMEOUT = "HINDSIGHT_API_CONSOLIDATION_LLM_TIMEOUT"

 ENV_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
 ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
-ENV_EMBEDDINGS_LOCAL_FORCE_CPU = "HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU"
 ENV_EMBEDDINGS_TEI_URL = "HINDSIGHT_API_EMBEDDINGS_TEI_URL"
 ENV_EMBEDDINGS_OPENAI_API_KEY = "HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY"
 ENV_EMBEDDINGS_OPENAI_MODEL = "HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL"
@@ -85,7 +65,6 @@ ENV_RERANKER_LITELLM_MODEL = "HINDSIGHT_API_RERANKER_LITELLM_MODEL"

 ENV_RERANKER_PROVIDER = "HINDSIGHT_API_RERANKER_PROVIDER"
 ENV_RERANKER_LOCAL_MODEL = "HINDSIGHT_API_RERANKER_LOCAL_MODEL"
-ENV_RERANKER_LOCAL_FORCE_CPU = "HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU"
 ENV_RERANKER_LOCAL_MAX_CONCURRENT = "HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT"
 ENV_RERANKER_TEI_URL = "HINDSIGHT_API_RERANKER_TEI_URL"
 ENV_RERANKER_TEI_BATCH_SIZE = "HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE"
@@ -108,29 +87,21 @@ ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
 ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 ENV_MENTAL_MODEL_REFRESH_CONCURRENCY = "HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY"

-# OpenTelemetry tracing configuration
-ENV_OTEL_TRACES_ENABLED = "HINDSIGHT_API_OTEL_TRACES_ENABLED"
-ENV_OTEL_EXPORTER_OTLP_ENDPOINT = "HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT"
-ENV_OTEL_EXPORTER_OTLP_HEADERS = "HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS"
-ENV_OTEL_SERVICE_NAME = "HINDSIGHT_API_OTEL_SERVICE_NAME"
-ENV_OTEL_DEPLOYMENT_ENVIRONMENT = "HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT"
-
-# Vertex AI configuration
-ENV_LLM_VERTEXAI_PROJECT_ID = "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID"
-ENV_LLM_VERTEXAI_REGION = "HINDSIGHT_API_LLM_VERTEXAI_REGION"
-ENV_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY = "HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY"
+# Observation thresholds
+ENV_OBSERVATION_MIN_FACTS = "HINDSIGHT_API_OBSERVATION_MIN_FACTS"
+ENV_OBSERVATION_TOP_ENTITIES = "HINDSIGHT_API_OBSERVATION_TOP_ENTITIES"

 # 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_CUSTOM_INSTRUCTIONS = "HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"
+ENV_RETAIN_OBSERVATIONS_ASYNC = "HINDSIGHT_API_RETAIN_OBSERVATIONS_ASYNC"

-# Observations settings (consolidated knowledge from facts)
-ENV_ENABLE_OBSERVATIONS = "HINDSIGHT_API_ENABLE_OBSERVATIONS"
+# Mental models settings
+ENV_ENABLE_MENTAL_MODELS = "HINDSIGHT_API_ENABLE_MENTAL_MODELS"
+ENV_CONSOLIDATION_SIMILARITY_THRESHOLD = "HINDSIGHT_API_CONSOLIDATION_SIMILARITY_THRESHOLD"
 ENV_CONSOLIDATION_BATCH_SIZE = "HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE"
-ENV_CONSOLIDATION_MAX_TOKENS = "HINDSIGHT_API_CONSOLIDATION_MAX_TOKENS"

 # Optimization flags
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
@@ -150,52 +121,26 @@ ENV_WORKER_ENABLED = "HINDSIGHT_API_WORKER_ENABLED"
 ENV_WORKER_ID = "HINDSIGHT_API_WORKER_ID"
 ENV_WORKER_POLL_INTERVAL_MS = "HINDSIGHT_API_WORKER_POLL_INTERVAL_MS"
 ENV_WORKER_MAX_RETRIES = "HINDSIGHT_API_WORKER_MAX_RETRIES"
+ENV_WORKER_BATCH_SIZE = "HINDSIGHT_API_WORKER_BATCH_SIZE"
 ENV_WORKER_HTTP_PORT = "HINDSIGHT_API_WORKER_HTTP_PORT"
-ENV_WORKER_MAX_SLOTS = "HINDSIGHT_API_WORKER_MAX_SLOTS"
-ENV_WORKER_CONSOLIDATION_MAX_SLOTS = "HINDSIGHT_API_WORKER_CONSOLIDATION_MAX_SLOTS"

 # Reflect agent settings
 ENV_REFLECT_MAX_ITERATIONS = "HINDSIGHT_API_REFLECT_MAX_ITERATIONS"

 # Default values
 DEFAULT_DATABASE_URL = "pg0"
-DEFAULT_DATABASE_SCHEMA = "public"
 DEFAULT_LLM_PROVIDER = "openai"
-
-# Provider-specific default models
-PROVIDER_DEFAULT_MODELS = {
-    "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": "gemini-2.0-flash-001",
-    "openai-codex": "gpt-5.2-codex",
-    "claude-code": "claude-sonnet-4-5-20250929",
-    "mock": "mock-model",
-}
-DEFAULT_LLM_MODEL = "o3-mini"  # Fallback if provider not in table
+DEFAULT_LLM_MODEL = "gpt-5-mini"
 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
-DEFAULT_LLM_MAX_BACKOFF = 60.0  # Max backoff cap in seconds for retry exponential backoff
 DEFAULT_LLM_TIMEOUT = 120.0  # seconds

-# Vertex AI defaults
-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
-
 DEFAULT_EMBEDDINGS_PROVIDER = "local"
 DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"
-DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU = False  # Force CPU mode for local embeddings (avoids MPS/XPC issues on macOS)
 DEFAULT_EMBEDDINGS_OPENAI_MODEL = "text-embedding-3-small"
 DEFAULT_EMBEDDING_DIMENSION = 384

 DEFAULT_RERANKER_PROVIDER = "local"
 DEFAULT_RERANKER_LOCAL_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
-DEFAULT_RERANKER_LOCAL_FORCE_CPU = False  # Force CPU mode for local reranker (avoids MPS/XPC issues on macOS)
 DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4  # Limit concurrent CPU-bound reranking to prevent thrashing
 DEFAULT_RERANKER_TEI_BATCH_SIZE = 128
 DEFAULT_RERANKER_TEI_MAX_CONCURRENT = 8
@@ -224,18 +169,22 @@ DEFAULT_RECALL_CONNECTION_BUDGET = 4  # Max concurrent DB connections per recall
 DEFAULT_MCP_LOCAL_BANK_ID = "mcp"
 DEFAULT_MENTAL_MODEL_REFRESH_CONCURRENCY = 8  # Max concurrent mental model refreshes

+# Observation thresholds
+DEFAULT_OBSERVATION_MIN_FACTS = 5  # Min facts required to generate entity observations
+DEFAULT_OBSERVATION_TOP_ENTITIES = 5  # Max entities to process per retain batch
+
 # Retain settings
 DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 64000  # Max tokens for fact extraction LLM call
 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_CUSTOM_INSTRUCTIONS = None  # Custom extraction guidelines (only used when mode="custom")
+DEFAULT_RETAIN_EXTRACTION_MODE = "concise"  # Extraction mode: "concise" or "verbose"
+RETAIN_EXTRACTION_MODES = ("concise", "verbose")  # Allowed extraction modes
+DEFAULT_RETAIN_OBSERVATIONS_ASYNC = False  # Run observation generation async (after retain completes)

-# Observations defaults (consolidated knowledge from facts)
-DEFAULT_ENABLE_OBSERVATIONS = True  # Observations enabled by default
+# Mental models defaults
+DEFAULT_ENABLE_MENTAL_MODELS = False  # Mental models disabled by default (experimental)
+DEFAULT_CONSOLIDATION_SIMILARITY_THRESHOLD = 0.75  # Minimum similarity to consider a learning related
 DEFAULT_CONSOLIDATION_BATCH_SIZE = 50  # Memories to load per batch (internal memory optimization)
-DEFAULT_CONSOLIDATION_MAX_TOKENS = 1024  # Max tokens for recall when finding related observations

 # Database migrations
 DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
@@ -251,18 +200,12 @@ DEFAULT_WORKER_ENABLED = True  # API runs worker by default (standalone mode)
 DEFAULT_WORKER_ID = None  # Will use hostname if not specified
 DEFAULT_WORKER_POLL_INTERVAL_MS = 500  # Poll database every 500ms
 DEFAULT_WORKER_MAX_RETRIES = 3  # Max retries before marking task failed
+DEFAULT_WORKER_BATCH_SIZE = 10  # Tasks to claim per poll cycle
 DEFAULT_WORKER_HTTP_PORT = 8889  # HTTP port for worker metrics/health
-DEFAULT_WORKER_MAX_SLOTS = 10  # Total concurrent tasks per worker
-DEFAULT_WORKER_CONSOLIDATION_MAX_SLOTS = 2  # Max concurrent consolidation tasks per worker

 # Reflect agent settings
 DEFAULT_REFLECT_MAX_ITERATIONS = 10  # Max tool call iterations before forcing response

-# OpenTelemetry tracing configuration
-DEFAULT_OTEL_TRACES_ENABLED = False  # Disabled by default for backward compatibility
-DEFAULT_OTEL_SERVICE_NAME = "hindsight-api"
-DEFAULT_OTEL_DEPLOYMENT_ENVIRONMENT = "development"
-
 # Default MCP tool descriptions (can be customized via env vars)
 DEFAULT_MCP_RETAIN_DESCRIPTION = """Store important information to long-term memory.

@@ -329,18 +272,12 @@ def _validate_extraction_mode(mode: str) -> str:
    return mode_lower


-def _get_default_model_for_provider(provider: str) -> str:
-    """Get the default model for a given provider."""
-    return PROVIDER_DEFAULT_MODELS.get(provider.lower(), DEFAULT_LLM_MODEL)
-
-
@dataclass
 class HindsightConfig:
    """Configuration container for Hindsight API."""

    # Database
    database_url: str
-    database_schema: str

    # LLM (default, used as fallback for per-operation config)
    llm_provider: str
@@ -348,51 +285,27 @@ class HindsightConfig:
    llm_model: str
    llm_base_url: str | None
    llm_max_concurrent: int
-    llm_max_retries: int
-    llm_initial_backoff: float
-    llm_max_backoff: float
    llm_timeout: float

-    # Vertex AI configuration
-    llm_vertexai_project_id: str | None
-    llm_vertexai_region: str
-    llm_vertexai_service_account_key: str | None
-
    # Per-operation LLM configuration (None = use default LLM config)
    retain_llm_provider: str | None
    retain_llm_api_key: str | None
    retain_llm_model: str | None
    retain_llm_base_url: str | None
-    retain_llm_max_concurrent: int | None
-    retain_llm_max_retries: int | None
-    retain_llm_initial_backoff: float | None
-    retain_llm_max_backoff: float | None
-    retain_llm_timeout: float | None

    reflect_llm_provider: str | None
    reflect_llm_api_key: str | None
    reflect_llm_model: str | None
    reflect_llm_base_url: str | None
-    reflect_llm_max_concurrent: int | None
-    reflect_llm_max_retries: int | None
-    reflect_llm_initial_backoff: float | None
-    reflect_llm_max_backoff: float | None
-    reflect_llm_timeout: float | None

    consolidation_llm_provider: str | None
    consolidation_llm_api_key: str | None
    consolidation_llm_model: str | None
    consolidation_llm_base_url: str | None
-    consolidation_llm_max_concurrent: int | None
-    consolidation_llm_max_retries: int | None
-    consolidation_llm_initial_backoff: float | None
-    consolidation_llm_max_backoff: float | None
-    consolidation_llm_timeout: float | None

    # Embeddings
    embeddings_provider: str
    embeddings_local_model: str
-    embeddings_local_force_cpu: bool
    embeddings_tei_url: str | None
    embeddings_openai_base_url: str | None
    embeddings_cohere_base_url: str | None
@@ -400,8 +313,6 @@ class HindsightConfig:
    # Reranker
    reranker_provider: str
    reranker_local_model: str
-    reranker_local_force_cpu: bool
-    reranker_local_max_concurrent: int
    reranker_tei_url: str | None
    reranker_tei_batch_size: int
    reranker_tei_max_concurrent: int
@@ -422,17 +333,21 @@ class HindsightConfig:
    recall_connection_budget: int
    mental_model_refresh_concurrency: int

+    # Observation thresholds
+    observation_min_facts: int
+    observation_top_entities: int
+
    # Retain settings
    retain_max_completion_tokens: int
    retain_chunk_size: int
    retain_extract_causal_links: bool
    retain_extraction_mode: str
-    retain_custom_instructions: str | None
+    retain_observations_async: bool

-    # Observations settings (consolidated knowledge from facts)
-    enable_observations: bool
+    # Mental models settings
+    enable_mental_models: bool
+    consolidation_similarity_threshold: float
    consolidation_batch_size: int
-    consolidation_max_tokens: int

    # Optimization flags
    skip_llm_verification: bool
@@ -452,153 +367,47 @@ class HindsightConfig:
    worker_id: str | None
    worker_poll_interval_ms: int
    worker_max_retries: int
+    worker_batch_size: int
    worker_http_port: int
-    worker_max_slots: int
-    worker_consolidation_max_slots: int

    # Reflect agent settings
    reflect_max_iterations: int

-    # OpenTelemetry tracing configuration
-    otel_traces_enabled: bool
-    otel_exporter_otlp_endpoint: str | None
-    otel_exporter_otlp_headers: str | None
-    otel_service_name: str
-    otel_deployment_environment: str
-
-    def validate(self) -> None:
-        """Validate configuration values and raise errors for invalid combinations."""
-        # RETAIN_MAX_COMPLETION_TOKENS must be greater than RETAIN_CHUNK_SIZE
-        # to ensure the LLM has enough output capacity to extract facts from chunks
-        if self.retain_max_completion_tokens <= self.retain_chunk_size:
-            raise ValueError(
-                f"Invalid configuration: HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS "
-                f"({self.retain_max_completion_tokens}) must be greater than "
-                f"HINDSIGHT_API_RETAIN_CHUNK_SIZE ({self.retain_chunk_size}). "
-                f"\n\nYou have two options to fix this:"
-                f"\n  1. Increase HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS to a value > {self.retain_chunk_size}"
-                f"\n  2. Use a model that supports at least {self.retain_max_completion_tokens} output tokens"
-                f"\n     (current model: {self.retain_llm_model or self.llm_model}, "
-                f"provider: {self.retain_llm_provider or self.llm_provider})"
-            )
-
    @classmethod
    def from_env(cls) -> "HindsightConfig":
        """Create configuration from environment variables."""
-        # Get provider first to determine default model
-        llm_provider = os.getenv(ENV_LLM_PROVIDER, DEFAULT_LLM_PROVIDER)
-        llm_model = os.getenv(ENV_LLM_MODEL) or _get_default_model_for_provider(llm_provider)
-
-        config = cls(
+        return cls(
            # Database
            database_url=os.getenv(ENV_DATABASE_URL, DEFAULT_DATABASE_URL),
-            database_schema=os.getenv(ENV_DATABASE_SCHEMA, DEFAULT_DATABASE_SCHEMA),
            # LLM
-            llm_provider=llm_provider,
+            llm_provider=os.getenv(ENV_LLM_PROVIDER, DEFAULT_LLM_PROVIDER),
            llm_api_key=os.getenv(ENV_LLM_API_KEY),
-            llm_model=llm_model,
+            llm_model=os.getenv(ENV_LLM_MODEL, DEFAULT_LLM_MODEL),
            llm_base_url=os.getenv(ENV_LLM_BASE_URL) or None,
            llm_max_concurrent=int(os.getenv(ENV_LLM_MAX_CONCURRENT, str(DEFAULT_LLM_MAX_CONCURRENT))),
-            llm_max_retries=int(os.getenv(ENV_LLM_MAX_RETRIES, str(DEFAULT_LLM_MAX_RETRIES))),
-            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))),
-            # 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,
            # 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,
-            retain_llm_model=os.getenv(ENV_RETAIN_LLM_MODEL)
-            or (
-                _get_default_model_for_provider(os.getenv(ENV_RETAIN_LLM_PROVIDER))
-                if os.getenv(ENV_RETAIN_LLM_PROVIDER)
-                else None
-            ),
+            retain_llm_model=os.getenv(ENV_RETAIN_LLM_MODEL) or None,
            retain_llm_base_url=os.getenv(ENV_RETAIN_LLM_BASE_URL) or None,
-            retain_llm_max_concurrent=int(os.getenv(ENV_RETAIN_LLM_MAX_CONCURRENT))
-            if os.getenv(ENV_RETAIN_LLM_MAX_CONCURRENT)
-            else None,
-            retain_llm_max_retries=int(os.getenv(ENV_RETAIN_LLM_MAX_RETRIES))
-            if os.getenv(ENV_RETAIN_LLM_MAX_RETRIES)
-            else None,
-            retain_llm_initial_backoff=float(os.getenv(ENV_RETAIN_LLM_INITIAL_BACKOFF))
-            if os.getenv(ENV_RETAIN_LLM_INITIAL_BACKOFF)
-            else None,
-            retain_llm_max_backoff=float(os.getenv(ENV_RETAIN_LLM_MAX_BACKOFF))
-            if os.getenv(ENV_RETAIN_LLM_MAX_BACKOFF)
-            else None,
-            retain_llm_timeout=float(os.getenv(ENV_RETAIN_LLM_TIMEOUT)) if os.getenv(ENV_RETAIN_LLM_TIMEOUT) else None,
            reflect_llm_provider=os.getenv(ENV_REFLECT_LLM_PROVIDER) or None,
            reflect_llm_api_key=os.getenv(ENV_REFLECT_LLM_API_KEY) or None,
-            reflect_llm_model=os.getenv(ENV_REFLECT_LLM_MODEL)
-            or (
-                _get_default_model_for_provider(os.getenv(ENV_REFLECT_LLM_PROVIDER))
-                if os.getenv(ENV_REFLECT_LLM_PROVIDER)
-                else None
-            ),
+            reflect_llm_model=os.getenv(ENV_REFLECT_LLM_MODEL) or None,
            reflect_llm_base_url=os.getenv(ENV_REFLECT_LLM_BASE_URL) or None,
-            reflect_llm_max_concurrent=int(os.getenv(ENV_REFLECT_LLM_MAX_CONCURRENT))
-            if os.getenv(ENV_REFLECT_LLM_MAX_CONCURRENT)
-            else None,
-            reflect_llm_max_retries=int(os.getenv(ENV_REFLECT_LLM_MAX_RETRIES))
-            if os.getenv(ENV_REFLECT_LLM_MAX_RETRIES)
-            else None,
-            reflect_llm_initial_backoff=float(os.getenv(ENV_REFLECT_LLM_INITIAL_BACKOFF))
-            if os.getenv(ENV_REFLECT_LLM_INITIAL_BACKOFF)
-            else None,
-            reflect_llm_max_backoff=float(os.getenv(ENV_REFLECT_LLM_MAX_BACKOFF))
-            if os.getenv(ENV_REFLECT_LLM_MAX_BACKOFF)
-            else None,
-            reflect_llm_timeout=float(os.getenv(ENV_REFLECT_LLM_TIMEOUT))
-            if os.getenv(ENV_REFLECT_LLM_TIMEOUT)
-            else None,
            consolidation_llm_provider=os.getenv(ENV_CONSOLIDATION_LLM_PROVIDER) or None,
            consolidation_llm_api_key=os.getenv(ENV_CONSOLIDATION_LLM_API_KEY) or None,
-            consolidation_llm_model=os.getenv(ENV_CONSOLIDATION_LLM_MODEL)
-            or (
-                _get_default_model_for_provider(os.getenv(ENV_CONSOLIDATION_LLM_PROVIDER))
-                if os.getenv(ENV_CONSOLIDATION_LLM_PROVIDER)
-                else None
-            ),
+            consolidation_llm_model=os.getenv(ENV_CONSOLIDATION_LLM_MODEL) or None,
            consolidation_llm_base_url=os.getenv(ENV_CONSOLIDATION_LLM_BASE_URL) or None,
-            consolidation_llm_max_concurrent=int(os.getenv(ENV_CONSOLIDATION_LLM_MAX_CONCURRENT))
-            if os.getenv(ENV_CONSOLIDATION_LLM_MAX_CONCURRENT)
-            else None,
-            consolidation_llm_max_retries=int(os.getenv(ENV_CONSOLIDATION_LLM_MAX_RETRIES))
-            if os.getenv(ENV_CONSOLIDATION_LLM_MAX_RETRIES)
-            else None,
-            consolidation_llm_initial_backoff=float(os.getenv(ENV_CONSOLIDATION_LLM_INITIAL_BACKOFF))
-            if os.getenv(ENV_CONSOLIDATION_LLM_INITIAL_BACKOFF)
-            else None,
-            consolidation_llm_max_backoff=float(os.getenv(ENV_CONSOLIDATION_LLM_MAX_BACKOFF))
-            if os.getenv(ENV_CONSOLIDATION_LLM_MAX_BACKOFF)
-            else None,
-            consolidation_llm_timeout=float(os.getenv(ENV_CONSOLIDATION_LLM_TIMEOUT))
-            if os.getenv(ENV_CONSOLIDATION_LLM_TIMEOUT)
-            else None,
            # Embeddings
            embeddings_provider=os.getenv(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER),
            embeddings_local_model=os.getenv(ENV_EMBEDDINGS_LOCAL_MODEL, DEFAULT_EMBEDDINGS_LOCAL_MODEL),
-            embeddings_local_force_cpu=os.getenv(
-                ENV_EMBEDDINGS_LOCAL_FORCE_CPU, str(DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU)
-            ).lower()
-            in ("true", "1"),
            embeddings_tei_url=os.getenv(ENV_EMBEDDINGS_TEI_URL),
            embeddings_openai_base_url=os.getenv(ENV_EMBEDDINGS_OPENAI_BASE_URL) or None,
            embeddings_cohere_base_url=os.getenv(ENV_EMBEDDINGS_COHERE_BASE_URL) 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),
-            reranker_local_force_cpu=os.getenv(
-                ENV_RERANKER_LOCAL_FORCE_CPU, str(DEFAULT_RERANKER_LOCAL_FORCE_CPU)
-            ).lower()
-            in ("true", "1"),
-            reranker_local_max_concurrent=int(
-                os.getenv(ENV_RERANKER_LOCAL_MAX_CONCURRENT, str(DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT))
-            ),
            reranker_tei_url=os.getenv(ENV_RERANKER_TEI_URL),
            reranker_tei_batch_size=int(os.getenv(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE))),
            reranker_tei_max_concurrent=int(
@@ -625,6 +434,11 @@ class HindsightConfig:
            # Optimization flags
            skip_llm_verification=os.getenv(ENV_SKIP_LLM_VERIFICATION, "false").lower() == "true",
            lazy_reranker=os.getenv(ENV_LAZY_RERANKER, "false").lower() == "true",
+            # Observation thresholds
+            observation_min_facts=int(os.getenv(ENV_OBSERVATION_MIN_FACTS, str(DEFAULT_OBSERVATION_MIN_FACTS))),
+            observation_top_entities=int(
+                os.getenv(ENV_OBSERVATION_TOP_ENTITIES, str(DEFAULT_OBSERVATION_TOP_ENTITIES))
+            ),
            # Retain settings
            retain_max_completion_tokens=int(
                os.getenv(ENV_RETAIN_MAX_COMPLETION_TOKENS, str(DEFAULT_RETAIN_MAX_COMPLETION_TOKENS))
@@ -637,15 +451,19 @@ class HindsightConfig:
            retain_extraction_mode=_validate_extraction_mode(
                os.getenv(ENV_RETAIN_EXTRACTION_MODE, DEFAULT_RETAIN_EXTRACTION_MODE)
            ),
-            retain_custom_instructions=os.getenv(ENV_RETAIN_CUSTOM_INSTRUCTIONS) or DEFAULT_RETAIN_CUSTOM_INSTRUCTIONS,
-            # Observations settings (consolidated knowledge from facts)
-            enable_observations=os.getenv(ENV_ENABLE_OBSERVATIONS, str(DEFAULT_ENABLE_OBSERVATIONS)).lower() == "true",
+            retain_observations_async=os.getenv(
+                ENV_RETAIN_OBSERVATIONS_ASYNC, str(DEFAULT_RETAIN_OBSERVATIONS_ASYNC)
+            ).lower()
+            == "true",
+            # Mental models settings
+            enable_mental_models=os.getenv(ENV_ENABLE_MENTAL_MODELS, str(DEFAULT_ENABLE_MENTAL_MODELS)).lower()
+            == "true",
+            consolidation_similarity_threshold=float(
+                os.getenv(ENV_CONSOLIDATION_SIMILARITY_THRESHOLD, str(DEFAULT_CONSOLIDATION_SIMILARITY_THRESHOLD))
+            ),
            consolidation_batch_size=int(
                os.getenv(ENV_CONSOLIDATION_BATCH_SIZE, str(DEFAULT_CONSOLIDATION_BATCH_SIZE))
            ),
-            consolidation_max_tokens=int(
-                os.getenv(ENV_CONSOLIDATION_MAX_TOKENS, str(DEFAULT_CONSOLIDATION_MAX_TOKENS))
-            ),
            # Database migrations
            run_migrations_on_startup=os.getenv(ENV_RUN_MIGRATIONS_ON_STARTUP, "true").lower() == "true",
            # Database connection pool
@@ -658,23 +476,11 @@ class HindsightConfig:
            worker_id=os.getenv(ENV_WORKER_ID) or DEFAULT_WORKER_ID,
            worker_poll_interval_ms=int(os.getenv(ENV_WORKER_POLL_INTERVAL_MS, str(DEFAULT_WORKER_POLL_INTERVAL_MS))),
            worker_max_retries=int(os.getenv(ENV_WORKER_MAX_RETRIES, str(DEFAULT_WORKER_MAX_RETRIES))),
+            worker_batch_size=int(os.getenv(ENV_WORKER_BATCH_SIZE, str(DEFAULT_WORKER_BATCH_SIZE))),
            worker_http_port=int(os.getenv(ENV_WORKER_HTTP_PORT, str(DEFAULT_WORKER_HTTP_PORT))),
-            worker_max_slots=int(os.getenv(ENV_WORKER_MAX_SLOTS, str(DEFAULT_WORKER_MAX_SLOTS))),
-            worker_consolidation_max_slots=int(
-                os.getenv(ENV_WORKER_CONSOLIDATION_MAX_SLOTS, str(DEFAULT_WORKER_CONSOLIDATION_MAX_SLOTS))
-            ),
            # Reflect agent settings
            reflect_max_iterations=int(os.getenv(ENV_REFLECT_MAX_ITERATIONS, str(DEFAULT_REFLECT_MAX_ITERATIONS))),
-            # OpenTelemetry tracing configuration
-            otel_traces_enabled=os.getenv(ENV_OTEL_TRACES_ENABLED, str(DEFAULT_OTEL_TRACES_ENABLED)).lower()
-            in ("true", "1", "yes"),
-            otel_exporter_otlp_endpoint=os.getenv(ENV_OTEL_EXPORTER_OTLP_ENDPOINT) or None,
-            otel_exporter_otlp_headers=os.getenv(ENV_OTEL_EXPORTER_OTLP_HEADERS) or None,
-            otel_service_name=os.getenv(ENV_OTEL_SERVICE_NAME, DEFAULT_OTEL_SERVICE_NAME),
-            otel_deployment_environment=os.getenv(ENV_OTEL_DEPLOYMENT_ENVIRONMENT, DEFAULT_OTEL_DEPLOYMENT_ENVIRONMENT),
        )
-        config.validate()
-        return config

    def get_llm_base_url(self) -> str:
        """Get the LLM base URL, with provider-specific defaults."""
@@ -729,7 +535,7 @@ class HindsightConfig:

    def log_config(self) -> None:
        """Log the current configuration (without sensitive values)."""
-        logger.info(f"Database: {self.database_url} (schema: {self.database_schema})")
+        logger.info(f"Database: {self.database_url}")
        logger.info(f"LLM: provider={self.llm_provider}, model={self.llm_model}")
        if self.retain_llm_provider or self.retain_llm_model:
            retain_provider = self.retain_llm_provider or self.llm_provider
@@ -1,10 +1,11 @@
 """
 Daemon mode support for Hindsight API.

-Provides idle timeout for running as a background daemon.
+Provides idle timeout and lockfile management for running as a background daemon.
 """

 import asyncio
+import fcntl
 import logging
 import os
 import sys
@@ -14,11 +15,10 @@ from pathlib import Path
 logger = logging.getLogger(__name__)

 # Default daemon configuration
-DEFAULT_DAEMON_PORT = 8888
+DEFAULT_DAEMON_PORT = 8889
 DEFAULT_IDLE_TIMEOUT = 0  # 0 = no auto-exit (hindsight-embed passes its own timeout)
-
-# Allow override via environment variable for profile-specific logs
-DAEMON_LOG_PATH = Path(os.getenv("HINDSIGHT_API_DAEMON_LOG", str(Path.home() / ".hindsight" / "daemon.log")))
+LOCKFILE_PATH = Path.home() / ".hindsight" / "daemon.lock"
+DAEMON_LOG_PATH = Path.home() / ".hindsight" / "daemon.log"


 class IdleTimeoutMiddleware:
@@ -52,10 +52,82 @@ class IdleTimeoutMiddleware:
                logger.info(f"Idle timeout reached ({self.idle_timeout}s), shutting down daemon")
                # Give a moment for any in-flight requests
                await asyncio.sleep(1)
-                # Send SIGTERM to ourselves to trigger graceful shutdown
-                import signal
+                os._exit(0)

-                os.kill(os.getpid(), signal.SIGTERM)
+
+class DaemonLock:
+    """
+    File-based lock to prevent multiple daemon instances.
+
+    Uses fcntl.flock for atomic locking on Unix systems.
+    """
+
+    def __init__(self, lockfile: Path = LOCKFILE_PATH):
+        self.lockfile = lockfile
+        self._fd = None
+
+    def acquire(self) -> bool:
+        """
+        Try to acquire the daemon lock.
+
+        Returns True if lock acquired, False if another daemon is running.
+        """
+        self.lockfile.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            self._fd = open(self.lockfile, "w")
+            fcntl.flock(self._fd.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            # Write PID for debugging
+            self._fd.write(str(os.getpid()))
+            self._fd.flush()
+            return True
+        except (IOError, OSError):
+            # Lock is held by another process
+            if self._fd:
+                self._fd.close()
+                self._fd = None
+            return False
+
+    def release(self):
+        """Release the daemon lock."""
+        if self._fd:
+            try:
+                fcntl.flock(self._fd.fileno(), fcntl.LOCK_UN)
+                self._fd.close()
+            except Exception:
+                pass
+            finally:
+                self._fd = None
+                # Remove lockfile
+                try:
+                    self.lockfile.unlink()
+                except Exception:
+                    pass
+
+    def is_locked(self) -> bool:
+        """Check if the lock is held by another process."""
+        if not self.lockfile.exists():
+            return False
+
+        try:
+            fd = open(self.lockfile, "r")
+            fcntl.flock(fd.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            # We got the lock, so no one else has it
+            fcntl.flock(fd.fileno(), fcntl.LOCK_UN)
+            fd.close()
+            return False
+        except (IOError, OSError):
+            return True
+
+    def get_pid(self) -> int | None:
+        """Get the PID of the daemon holding the lock."""
+        if not self.lockfile.exists():
+            return None
+        try:
+            with open(self.lockfile, "r") as f:
+                return int(f.read().strip())
+        except (ValueError, IOError):
+            return None


 def daemonize():
@@ -64,21 +136,16 @@ def daemonize():

    Uses double-fork technique to properly detach from terminal.
    """
-    # First fork - detach from parent
-    try:
-        pid = os.fork()
-        if pid > 0:
-            sys.exit(0)
-    except OSError as e:
-        sys.stderr.write(f"fork #1 failed: {e}\n")
-        sys.exit(1)
+    # First fork
+    pid = os.fork()
+    if pid > 0:
+        # Parent exits
+        sys.exit(0)

-    # Decouple from parent environment
-    os.chdir("/")
+    # Create new session
    os.setsid()
-    os.umask(0)

-    # Second fork - prevent zombie
+    # Second fork to prevent zombie processes
    pid = os.fork()
    if pid > 0:
        sys.exit(0)
@@ -111,3 +178,27 @@ def check_daemon_running(port: int = DEFAULT_DAEMON_PORT) -> bool:
        return result == 0
    except Exception:
        return False
+
+
+def stop_daemon(port: int = DEFAULT_DAEMON_PORT) -> bool:
+    """Stop a running daemon by sending SIGTERM to the process."""
+    lock = DaemonLock()
+    pid = lock.get_pid()
+
+    if pid is None:
+        return False
+
+    try:
+        import signal
+
+        os.kill(pid, signal.SIGTERM)
+        # Wait for process to exit
+        for _ in range(50):  # Wait up to 5 seconds
+            time.sleep(0.1)
+            try:
+                os.kill(pid, 0)  # Check if process exists
+            except OSError:
+                return True  # Process exited
+        return False
+    except OSError:
+        return False
@@ -1,8 +1,8 @@
 """Prompts for the consolidation engine."""

-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.
+CONSOLIDATION_SYSTEM_PROMPT = """You are a memory consolidation system. Your job is to convert facts into durable knowledge (mental models) and merge with existing knowledge when appropriate.

-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.
+You must output ONLY valid JSON with no markdown formatting, no code blocks, and no additional 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.
@@ -30,56 +30,62 @@ 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):
+## MERGE RULES (when comparing to existing mental models):
 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"
+2. CONTRADICTION: Opposite information about same topic → update with history (e.g., "used to X, now Y")
+3. UPDATE: New state replacing old state → update with history
+
+## TAG ROUTING RULES:
+Tags define visibility scopes. The fact and each mental model have tags (can be empty = global).
+
+| Fact Tags | Model Tags | Action |
+|-----------|------------|--------|
+| [alice] | [alice] | UPDATE the model (same scope) |
+| [alice] | [] | UPDATE the model (global absorbs all scopes) |
+| [alice] | [bob] | CREATE new untagged model (cross-scope insight) |
+| [] | [alice] | UPDATE the model (untagged facts can update any scope) |
+| [] | [] | UPDATE the model (global to global) |
+
+When NO existing model matches the fact's topic: CREATE new model with fact's tags.
+
+## MULTIPLE ACTIONS:
+One fact can trigger MULTIPLE actions. For example:
+- Update a scoped model [alice] about pizza preferences
+- AND update a global model [] about pizza in general
+
+Output an ARRAY of actions (can be empty, one, or many).

 ## 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"""
+- When merging contradictions, capture the CHANGE (before → after)
+- Keep mental models focused on ONE specific topic per person
+- Cross-scope insights (alice's fact about bob's topic) become UNTAGGED (global)
+- The "text" field MUST contain durable knowledge, not ephemeral state"""

 CONSOLIDATION_USER_PROMPT = """Analyze this new fact and consolidate into knowledge.
 {mission_section}
 NEW FACT: {fact_text}
+FACT TAGS: {fact_tags}

-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
+EXISTING MENTAL MODELS:
+{mental_models_text}

 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 []
+1. First, extract the DURABLE KNOWLEDGE from the fact (not ephemeral state like "user is at X")
+2. Then compare with existing mental models:
+   - If a model covers the same topic: UPDATE it with the new knowledge
+   - If no model covers the topic: CREATE a new one
+   - If fact is about different scope: apply tag routing rules

-Output JSON array of actions (the "text" field should use markdown formatting for structure):
+Output JSON array of actions (ALWAYS an array, even for single action):
 [
-  {{"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": "..."}}
+  {{"action": "update", "learning_id": "uuid", "text": "updated durable knowledge", "reason": "..."}},
+  {{"action": "create", "tags": ["tag"], "text": "new durable knowledge", "reason": "..."}}
 ]

-Return [] if fact contains no durable knowledge.
+If NO consolidation is needed (fact is purely ephemeral with no durable knowledge):
+[]

-IMPORTANT: Format the "text" field with markdown for better readability:
- Use headers, lists, bold/italic, tables where appropriate
- CRITICAL: Add blank lines before and after block elements (tables, code blocks, lists)
- Ensure proper spacing for markdown to render correctly"""
+If no models exist and fact contains durable knowledge:
+[{{"action": "create", "tags": {fact_tags}, "text": "durable knowledge text", "reason": "new topic"}}]"""
@@ -9,7 +9,6 @@ Configuration via environment variables - see hindsight_api.config for all env v
 import asyncio
 import logging
 import os
-import warnings
 from abc import ABC, abstractmethod
 from concurrent.futures import ThreadPoolExecutor

@@ -21,7 +20,6 @@ from ..config import (
    DEFAULT_RERANKER_FLASHRANK_CACHE_DIR,
    DEFAULT_RERANKER_FLASHRANK_MODEL,
    DEFAULT_RERANKER_LITELLM_MODEL,
-    DEFAULT_RERANKER_LOCAL_FORCE_CPU,
    DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT,
    DEFAULT_RERANKER_LOCAL_MODEL,
    DEFAULT_RERANKER_PROVIDER,
@@ -35,7 +33,6 @@ from ..config import (
    ENV_RERANKER_FLASHRANK_CACHE_DIR,
    ENV_RERANKER_FLASHRANK_MODEL,
    ENV_RERANKER_LITELLM_MODEL,
-    ENV_RERANKER_LOCAL_FORCE_CPU,
    ENV_RERANKER_LOCAL_MAX_CONCURRENT,
    ENV_RERANKER_LOCAL_MODEL,
    ENV_RERANKER_PROVIDER,
@@ -102,7 +99,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
    _executor: ThreadPoolExecutor | None = None
    _max_concurrent: int = 4  # Limit concurrent CPU-bound reranking calls

-    def __init__(self, model_name: str | None = None, max_concurrent: int = 4, force_cpu: bool = False):
+    def __init__(self, model_name: str | None = None, max_concurrent: int = 4):
        """
        Initialize local SentenceTransformers cross-encoder.

@@ -111,11 +108,8 @@ class LocalSTCrossEncoder(CrossEncoderModel):
                       Default: cross-encoder/ms-marco-MiniLM-L-6-v2
            max_concurrent: Maximum concurrent reranking calls (default: 2).
                           Higher values may cause CPU thrashing under load.
-            force_cpu: Force CPU mode (avoids MPS/XPC issues on macOS in daemon mode).
-                      Default: False
        """
        self.model_name = model_name or DEFAULT_RERANKER_LOCAL_MODEL
-        self.force_cpu = force_cpu
        self._model = None
        LocalSTCrossEncoder._max_concurrent = max_concurrent

@@ -145,46 +139,19 @@ class LocalSTCrossEncoder(CrossEncoderModel):
        # after loading, which conflicts with accelerate's device_map handling.
        import torch

-        # Force CPU mode if configured (used in daemon mode to avoid MPS/XPC issues on macOS)
-        if self.force_cpu:
-            device = "cpu"
-            logger.info("Reranker: forcing CPU mode (HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU=1)")
+        # Check for GPU (CUDA) or Apple Silicon (MPS)
+        has_gpu = torch.cuda.is_available() or (hasattr(torch.backends, "mps") and torch.backends.mps.is_available())
+
+        if has_gpu:
+            device = None  # Let sentence-transformers auto-detect GPU/MPS
        else:
-            # Check for GPU (CUDA) or Apple Silicon (MPS)
-            # Wrap in try-except to gracefully handle any device detection issues
-            # (e.g., in CI environments or when PyTorch is built without GPU support)
-            device = "cpu"  # Default to CPU
-            try:
-                has_gpu = torch.cuda.is_available() or (
-                    hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
-                )
-                if has_gpu:
-                    device = None  # Let sentence-transformers auto-detect GPU/MPS
-            except Exception as e:
-                logger.warning(f"Failed to detect GPU/MPS, falling back to CPU: {e}")
+            device = "cpu"

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

        # Initialize shared executor (limited workers naturally limits concurrency)
        if LocalSTCrossEncoder._executor is None:
@@ -196,11 +163,6 @@ class LocalSTCrossEncoder(CrossEncoderModel):
        else:
            logger.info("Reranker: local provider initialized (using existing executor)")

-    def _predict_sync(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """Synchronous prediction wrapper for thread pool execution."""
-        scores = self._model.predict(pairs, show_progress_bar=False)
-        return scores.tolist() if hasattr(scores, "tolist") else list(scores)
-
    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
        """
        Score query-document pairs for relevance.
@@ -218,11 +180,11 @@ class LocalSTCrossEncoder(CrossEncoderModel):

        # Use dedicated executor - limited workers naturally limits concurrency
        loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(
+        scores = await loop.run_in_executor(
            LocalSTCrossEncoder._executor,
-            self._predict_sync,
-            pairs,
+            lambda: self._model.predict(pairs, show_progress_bar=False),
        )
+        return scores.tolist() if hasattr(scores, "tolist") else list(scores)


 class RemoteTEICrossEncoder(CrossEncoderModel):
@@ -632,7 +594,7 @@ class FlashRankCrossEncoder(CrossEncoderModel):
            return

        try:
-            from flashrank import Ranker
+            from flashrank import Ranker  # type: ignore[import-untyped]
        except ImportError:
            raise ImportError("flashrank is required for FlashRankCrossEncoder. Install it with: pip install flashrank")

@@ -659,7 +621,7 @@ class FlashRankCrossEncoder(CrossEncoderModel):

    def _predict_sync(self, pairs: list[tuple[str, str]]) -> list[float]:
        """Synchronous predict - processes each query group."""
-        from flashrank import RerankRequest
+        from flashrank import RerankRequest  # type: ignore[import-untyped]

        if not pairs:
            return []
@@ -821,33 +783,29 @@ class LiteLLMCrossEncoder(CrossEncoderModel):

 def create_cross_encoder_from_env() -> CrossEncoderModel:
    """
-    Create a CrossEncoderModel instance based on configuration.
+    Create a CrossEncoderModel instance based on environment variables.

-    Reads configuration via get_config() to ensure consistency across the codebase.
+    See hindsight_api.config for environment variable names and defaults.

    Returns:
        Configured CrossEncoderModel instance
    """
-    from ..config import get_config
-
-    config = get_config()
-    provider = config.reranker_provider.lower()
+    provider = os.environ.get(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER).lower()

    if provider == "tei":
-        url = config.reranker_tei_url
+        url = os.environ.get(ENV_RERANKER_TEI_URL)
        if not url:
            raise ValueError(f"{ENV_RERANKER_TEI_URL} is required when {ENV_RERANKER_PROVIDER} is 'tei'")
-        return RemoteTEICrossEncoder(
-            base_url=url,
-            batch_size=config.reranker_tei_batch_size,
-            max_concurrent=config.reranker_tei_max_concurrent,
-        )
+        batch_size = int(os.environ.get(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE)))
+        max_concurrent = int(os.environ.get(ENV_RERANKER_TEI_MAX_CONCURRENT, str(DEFAULT_RERANKER_TEI_MAX_CONCURRENT)))
+        return RemoteTEICrossEncoder(base_url=url, batch_size=batch_size, max_concurrent=max_concurrent)
    elif provider == "local":
-        return LocalSTCrossEncoder(
-            model_name=config.reranker_local_model,
-            max_concurrent=config.reranker_local_max_concurrent,
-            force_cpu=config.reranker_local_force_cpu,
+        model = os.environ.get(ENV_RERANKER_LOCAL_MODEL)
+        model_name = model or DEFAULT_RERANKER_LOCAL_MODEL
+        max_concurrent = int(
+            os.environ.get(ENV_RERANKER_LOCAL_MAX_CONCURRENT, str(DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT))
        )
+        return LocalSTCrossEncoder(model_name=model_name, max_concurrent=max_concurrent)
    elif provider == "cohere":
        api_key = os.environ.get(ENV_COHERE_API_KEY)
        if not api_key:
@@ -11,7 +11,6 @@ Configuration via environment variables - see hindsight_api.config for all env v

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

 import httpx
@@ -19,7 +18,6 @@ import httpx
 from ..config import (
    DEFAULT_EMBEDDINGS_COHERE_MODEL,
    DEFAULT_EMBEDDINGS_LITELLM_MODEL,
-    DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU,
    DEFAULT_EMBEDDINGS_LOCAL_MODEL,
    DEFAULT_EMBEDDINGS_OPENAI_MODEL,
    DEFAULT_EMBEDDINGS_PROVIDER,
@@ -28,7 +26,6 @@ from ..config import (
    ENV_EMBEDDINGS_COHERE_BASE_URL,
    ENV_EMBEDDINGS_COHERE_MODEL,
    ENV_EMBEDDINGS_LITELLM_MODEL,
-    ENV_EMBEDDINGS_LOCAL_FORCE_CPU,
    ENV_EMBEDDINGS_LOCAL_MODEL,
    ENV_EMBEDDINGS_OPENAI_API_KEY,
    ENV_EMBEDDINGS_OPENAI_BASE_URL,
@@ -95,18 +92,15 @@ class LocalSTEmbeddings(Embeddings):
    The embedding dimension is auto-detected from the model.
    """

-    def __init__(self, model_name: str | None = None, force_cpu: bool = False):
+    def __init__(self, model_name: str | None = None):
        """
        Initialize local SentenceTransformers embeddings.

        Args:
            model_name: Name of the SentenceTransformer model to use.
                       Default: BAAI/bge-small-en-v1.5
-            force_cpu: Force CPU mode (avoids MPS/XPC issues on macOS in daemon mode).
-                      Default: False
        """
        self.model_name = model_name or DEFAULT_EMBEDDINGS_LOCAL_MODEL
-        self.force_cpu = force_cpu
        self._model = None
        self._dimension: int | None = None

@@ -140,46 +134,19 @@ class LocalSTEmbeddings(Embeddings):
        # which can cause issues when accelerate is installed but no GPU is available.
        import torch

-        # Force CPU mode if configured (used in daemon mode to avoid MPS/XPC issues on macOS)
-        if self.force_cpu:
-            device = "cpu"
-            logger.info("Embeddings: forcing CPU mode")
+        # Check for GPU (CUDA) or Apple Silicon (MPS)
+        has_gpu = torch.cuda.is_available() or (hasattr(torch.backends, "mps") and torch.backends.mps.is_available())
+
+        if has_gpu:
+            device = None  # Let sentence-transformers auto-detect GPU/MPS
        else:
-            # Check for GPU (CUDA) or Apple Silicon (MPS)
-            # Wrap in try-except to gracefully handle any device detection issues
-            # (e.g., in CI environments or when PyTorch is built without GPU support)
-            device = "cpu"  # Default to CPU
-            try:
-                has_gpu = torch.cuda.is_available() or (
-                    hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
-                )
-                if has_gpu:
-                    device = None  # Let sentence-transformers auto-detect GPU/MPS
-            except Exception as e:
-                logger.warning(f"Failed to detect GPU/MPS, falling back to CPU: {e}")
+            device = "cpu"

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

        self._dimension = self._model.get_sentence_embedding_dimension()
        logger.info(f"Embeddings: local provider initialized (dim: {self._dimension})")
@@ -196,7 +163,6 @@ class LocalSTEmbeddings(Embeddings):
        """
        if self._model is None:
            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-
        embeddings = self._model.encode(texts, convert_to_numpy=True, show_progress_bar=False)
        return [emb.tolist() for emb in embeddings]

@@ -563,7 +529,7 @@ class CohereEmbeddings(Embeddings):
                model=self.model,
                input_type=self.input_type,
            )
-            if response.embeddings and isinstance(response.embeddings, list):
+            if response.embeddings:
                self._dimension = len(response.embeddings[0])

        logger.info(f"Embeddings: Cohere provider initialized (model: {self.model}, dim: {self._dimension})")
@@ -720,28 +686,24 @@ class LiteLLMEmbeddings(Embeddings):

 def create_embeddings_from_env() -> Embeddings:
    """
-    Create an Embeddings instance based on configuration.
+    Create an Embeddings instance based on environment variables.

-    Reads configuration via get_config() to ensure consistency across the codebase.
+    See hindsight_api.config for environment variable names and defaults.

    Returns:
        Configured Embeddings instance
    """
-    from ..config import get_config
-
-    config = get_config()
-    provider = config.embeddings_provider.lower()
+    provider = os.environ.get(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER).lower()

    if provider == "tei":
-        url = config.embeddings_tei_url
+        url = os.environ.get(ENV_EMBEDDINGS_TEI_URL)
        if not url:
            raise ValueError(f"{ENV_EMBEDDINGS_TEI_URL} is required when {ENV_EMBEDDINGS_PROVIDER} is 'tei'")
        return RemoteTEIEmbeddings(base_url=url)
    elif provider == "local":
-        return LocalSTEmbeddings(
-            model_name=config.embeddings_local_model,
-            force_cpu=config.embeddings_local_force_cpu,
-        )
+        model = os.environ.get(ENV_EMBEDDINGS_LOCAL_MODEL)
+        model_name = model or DEFAULT_EMBEDDINGS_LOCAL_MODEL
+        return LocalSTEmbeddings(model_name=model_name)
    elif provider == "openai":
        # Use dedicated embeddings API key, or fall back to LLM API key
        api_key = os.environ.get(ENV_EMBEDDINGS_OPENAI_API_KEY) or os.environ.get(ENV_LLM_API_KEY)
@@ -442,6 +442,49 @@ class MemoryEngineInterface(ABC):
        """
        ...

+    @abstractmethod
+    async def get_entity_observations(
+        self,
+        bank_id: str,
+        entity_id: str,
+        *,
+        limit: int = 10,
+        request_context: "RequestContext",
+    ) -> list[Any]:
+        """
+        Get observations for an entity.
+
+        Args:
+            bank_id: The memory bank ID.
+            entity_id: The entity ID.
+            limit: Maximum observations.
+            request_context: Request context for authentication.
+
+        Returns:
+            List of EntityObservation objects.
+        """
+        ...
+
+    @abstractmethod
+    async def regenerate_entity_observations(
+        self,
+        bank_id: str,
+        entity_id: str,
+        entity_name: str,
+        *,
+        request_context: "RequestContext",
+    ) -> None:
+        """
+        Regenerate observations for an entity.
+
+        Args:
+            bank_id: The memory bank ID.
+            entity_id: The entity ID.
+            entity_name: The entity's canonical name.
+            request_context: Request context for authentication.
+        """
+        ...
+
    # =========================================================================
    # Statistics & Operations
    # =========================================================================
@@ -1,146 +0,0 @@
-"""
-Abstract interface for LLM providers.
-
-This module defines the interface that all LLM providers must implement,
-enabling support for multiple LLM backends (OpenAI, Anthropic, Gemini, Codex, etc.)
-"""
-
-from abc import ABC, abstractmethod
-from typing import Any
-
-from .response_models import LLMToolCallResult, TokenUsage
-
-
-class LLMInterface(ABC):
-    """
-    Abstract interface for LLM providers.
-
-    All LLM provider implementations must inherit from this class and implement
-    the required methods.
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        **kwargs: Any,
-    ):
-        """
-        Initialize LLM provider.
-
-        Args:
-            provider: Provider name (e.g., "openai", "codex", "anthropic", "gemini").
-            api_key: API key or authentication token.
-            base_url: Base URL for the API.
-            model: Model name.
-            reasoning_effort: Reasoning effort level for supported providers.
-            **kwargs: Additional provider-specific parameters.
-        """
-        self.provider = provider.lower()
-        self.api_key = api_key
-        self.base_url = base_url
-        self.model = model
-        self.reasoning_effort = reasoning_effort
-
-    @abstractmethod
-    async def verify_connection(self) -> None:
-        """
-        Verify that the LLM provider is configured correctly by making a simple test call.
-
-        Raises:
-            RuntimeError: If the connection test fails.
-        """
-        pass
-
-    @abstractmethod
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Make an LLM API call with retry logic.
-
-        Args:
-            messages: List of message dicts with 'role' and 'content'.
-            response_format: Optional Pydantic model for structured output.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            skip_validation: Return raw JSON without Pydantic validation.
-            strict_schema: Use strict JSON schema enforcement (OpenAI only).
-            return_usage: If True, return tuple (result, TokenUsage) instead of just result.
-
-        Returns:
-            If return_usage=False: Parsed response if response_format is provided, otherwise text content.
-            If return_usage=True: Tuple of (result, TokenUsage) with token counts.
-
-        Raises:
-            OutputTooLongError: If output exceeds token limits.
-            Exception: Re-raises API errors after retries exhausted.
-        """
-        pass
-
-    @abstractmethod
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make an LLM API call with tool/function calling support.
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            tool_choice: How to choose tools - "auto", "none", "required", or specific function.
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        pass
-
-    @abstractmethod
-    async def cleanup(self) -> None:
-        """Clean up resources (close connections, etc.)."""
-        pass
-
-
-class OutputTooLongError(Exception):
-    """
-    Bridge exception raised when LLM output exceeds token limits.
-
-    This wraps provider-specific errors (e.g., OpenAI's LengthFinishReasonError)
-    to allow callers to handle output length issues without depending on
-    provider-specific implementations.
-    """
-
-    pass
@@ -1,14 +0,0 @@
-"""
-LLM provider implementations.
-
-This package contains concrete implementations of the LLMInterface for various providers.
-"""
-
-from .anthropic_llm import AnthropicLLM
-from .claude_code_llm import ClaudeCodeLLM
-from .codex_llm import CodexLLM
-from .gemini_llm import GeminiLLM
-from .mock_llm import MockLLM
-from .openai_compatible_llm import OpenAICompatibleLLM
-
-__all__ = ["AnthropicLLM", "ClaudeCodeLLM", "CodexLLM", "GeminiLLM", "MockLLM", "OpenAICompatibleLLM"]
@@ -1,477 +0,0 @@
-"""
-Anthropic LLM provider using the Anthropic Python SDK.
-
-This provider enables using Claude models from Anthropic with support for:
- Structured JSON output
- Tool/function calling with proper format conversion
- Extended thinking mode
- Retry logic with exponential backoff
-"""
-
-import asyncio
-import json
-import logging
-import time
-from typing import Any
-
-from hindsight_api.engine.llm_interface import LLMInterface, OutputTooLongError
-from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
-from hindsight_api.metrics import get_metrics_collector
-
-logger = logging.getLogger(__name__)
-
-
-class AnthropicLLM(LLMInterface):
-    """
-    LLM provider using Anthropic's Claude models.
-
-    Supports structured output, tool calling, and extended thinking mode.
-    Handles format conversion between OpenAI-style messages and Anthropic's format.
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        timeout: float = 300.0,
-        **kwargs: Any,
-    ):
-        """
-        Initialize Anthropic LLM provider.
-
-        Args:
-            provider: Provider name (should be "anthropic").
-            api_key: Anthropic API key.
-            base_url: Base URL for the API (optional, uses Anthropic default if empty).
-            model: Model name (e.g., "claude-sonnet-4-20250514").
-            reasoning_effort: Reasoning effort level (not used by Anthropic).
-            timeout: Request timeout in seconds.
-            **kwargs: Additional provider-specific parameters.
-        """
-        super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs)
-
-        if not self.api_key:
-            raise ValueError("API key is required for Anthropic provider")
-
-        # Import and initialize Anthropic client
-        try:
-            from anthropic import AsyncAnthropic
-
-            client_kwargs: dict[str, Any] = {"api_key": self.api_key}
-            if self.base_url:
-                client_kwargs["base_url"] = self.base_url
-            if timeout:
-                client_kwargs["timeout"] = timeout
-
-            self._client = AsyncAnthropic(**client_kwargs)
-            logger.info(f"Anthropic client initialized for model: {self.model}")
-        except ImportError as e:
-            raise RuntimeError("Anthropic SDK not installed. Run: uv add anthropic or pip install anthropic") from e
-
-    async def verify_connection(self) -> None:
-        """
-        Verify that the Anthropic provider is configured correctly by making a simple test call.
-
-        Raises:
-            RuntimeError: If the connection test fails.
-        """
-        try:
-            test_messages = [{"role": "user", "content": "test"}]
-            await self.call(
-                messages=test_messages,
-                max_completion_tokens=10,
-                temperature=0.0,
-                scope="verification",
-                max_retries=0,
-            )
-            logger.info("Anthropic connection verified successfully")
-        except Exception as e:
-            logger.error(f"Anthropic connection verification failed: {e}")
-            raise RuntimeError(f"Failed to verify Anthropic connection: {e}") from e
-
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Make an LLM API call with retry logic.
-
-        Args:
-            messages: List of message dicts with 'role' and 'content'.
-            response_format: Optional Pydantic model for structured output.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            skip_validation: Return raw JSON without Pydantic validation.
-            strict_schema: Use strict JSON schema enforcement (not supported by Anthropic).
-            return_usage: If True, return tuple (result, TokenUsage) instead of just result.
-
-        Returns:
-            If return_usage=False: Parsed response if response_format is provided, otherwise text content.
-            If return_usage=True: Tuple of (result, TokenUsage) with token counts.
-
-        Raises:
-            OutputTooLongError: If output exceeds token limits.
-            Exception: Re-raises API errors after retries exhausted.
-        """
-        from anthropic import APIConnectionError, APIStatusError, RateLimitError
-
-        start_time = time.time()
-
-        # Convert OpenAI-style messages to Anthropic format
-        system_prompt = None
-        anthropic_messages = []
-
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                if system_prompt:
-                    system_prompt += "\n\n" + content
-                else:
-                    system_prompt = content
-            else:
-                anthropic_messages.append({"role": role, "content": content})
-
-        # Add JSON schema instruction if response_format is provided
-        if response_format is not None and hasattr(response_format, "model_json_schema"):
-            schema = response_format.model_json_schema()
-            schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
-            if system_prompt:
-                system_prompt += schema_msg
-            else:
-                system_prompt = schema_msg
-
-        # Prepare parameters
-        call_params: dict[str, Any] = {
-            "model": self.model,
-            "messages": anthropic_messages,
-            "max_tokens": max_completion_tokens if max_completion_tokens is not None else 4096,
-        }
-
-        if system_prompt:
-            call_params["system"] = system_prompt
-
-        if temperature is not None:
-            call_params["temperature"] = temperature
-
-        last_exception = None
-
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._client.messages.create(**call_params)
-
-                # Anthropic response content is a list of blocks
-                content = ""
-                for block in response.content:
-                    if block.type == "text":
-                        content += block.text
-
-                if response_format is not None:
-                    # Models may wrap JSON in markdown code blocks
-                    clean_content = content
-                    if "```json" in content:
-                        clean_content = content.split("```json")[1].split("```")[0].strip()
-                    elif "```" in content:
-                        clean_content = content.split("```")[1].split("```")[0].strip()
-
-                    try:
-                        json_data = json.loads(clean_content)
-                    except json.JSONDecodeError:
-                        # Fallback to parsing raw content if markdown stripping failed
-                        json_data = json.loads(content)
-
-                    if skip_validation:
-                        result = json_data
-                    else:
-                        result = response_format.model_validate(json_data)
-                else:
-                    result = content
-
-                # Record metrics and log slow calls
-                duration = time.time() - start_time
-                input_tokens = response.usage.input_tokens or 0 if response.usage else 0
-                output_tokens = response.usage.output_tokens or 0 if response.usage else 0
-                total_tokens = input_tokens + output_tokens
-
-                # Record LLM metrics
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                # Record trace span
-                from hindsight_api.tracing import _serialize_for_span, get_span_recorder
-
-                finish_reason = response.stop_reason if hasattr(response, "stop_reason") else None
-                span_recorder = get_span_recorder()
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=_serialize_for_span(result),
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    duration=duration,
-                    finish_reason=finish_reason,
-                    error=None,
-                )
-
-                # Log slow calls
-                if duration > 10.0:
-                    logger.info(
-                        f"slow llm call: scope={scope}, model={self.provider}/{self.model}, "
-                        f"input_tokens={input_tokens}, output_tokens={output_tokens}, "
-                        f"time={duration:.3f}s"
-                    )
-
-                if return_usage:
-                    token_usage = TokenUsage(
-                        input_tokens=input_tokens,
-                        output_tokens=output_tokens,
-                        total_tokens=total_tokens,
-                    )
-                    return result, token_usage
-                return result
-
-            except json.JSONDecodeError as e:
-                last_exception = e
-                if attempt < max_retries:
-                    logger.warning("Anthropic returned invalid JSON, retrying...")
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(f"Anthropic returned invalid JSON after {max_retries + 1} attempts")
-                    raise
-
-            except (APIConnectionError, RateLimitError, APIStatusError) as e:
-                # Fast fail on 401/403
-                if isinstance(e, APIStatusError) and e.status_code in (401, 403):
-                    logger.error(f"Anthropic auth error (HTTP {e.status_code}), not retrying: {str(e)}")
-                    raise
-
-                last_exception = e
-                if attempt < max_retries:
-                    # Check if it's a rate limit or server error
-                    should_retry = isinstance(e, (APIConnectionError, RateLimitError)) or (
-                        isinstance(e, APIStatusError) and e.status_code >= 500
-                    )
-
-                    if should_retry:
-                        backoff = min(initial_backoff * (2**attempt), max_backoff)
-                        jitter = backoff * 0.2 * (2 * (time.time() % 1) - 1)
-                        await asyncio.sleep(backoff + jitter)
-                        continue
-
-                logger.error(f"Anthropic API error after {max_retries + 1} attempts: {str(e)}")
-                raise
-
-            except Exception as e:
-                logger.error(f"Unexpected error during Anthropic call: {type(e).__name__}: {str(e)}")
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Anthropic call failed after all retries")
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make an LLM API call with tool/function calling support.
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            tool_choice: How to choose tools - "auto", "none", "required", or specific function.
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        from anthropic import APIConnectionError, APIStatusError
-
-        start_time = time.time()
-
-        # Convert OpenAI tool format to Anthropic format
-        anthropic_tools = []
-        for tool in tools:
-            func = tool.get("function", {})
-            anthropic_tools.append(
-                {
-                    "name": func.get("name", ""),
-                    "description": func.get("description", ""),
-                    "input_schema": func.get("parameters", {"type": "object", "properties": {}}),
-                }
-            )
-
-        # Convert messages - handle tool results
-        system_prompt = None
-        anthropic_messages = []
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                system_prompt = (system_prompt + "\n\n" + content) if system_prompt else content
-            elif role == "tool":
-                # Anthropic uses tool_result blocks
-                anthropic_messages.append(
-                    {
-                        "role": "user",
-                        "content": [
-                            {"type": "tool_result", "tool_use_id": msg.get("tool_call_id", ""), "content": content}
-                        ],
-                    }
-                )
-            elif role == "assistant" and msg.get("tool_calls"):
-                # Convert assistant tool calls
-                tool_use_blocks = []
-                for tc in msg["tool_calls"]:
-                    tool_use_blocks.append(
-                        {
-                            "type": "tool_use",
-                            "id": tc.get("id", ""),
-                            "name": tc.get("function", {}).get("name", ""),
-                            "input": json.loads(tc.get("function", {}).get("arguments", "{}")),
-                        }
-                    )
-                anthropic_messages.append({"role": "assistant", "content": tool_use_blocks})
-            else:
-                anthropic_messages.append({"role": role, "content": content})
-
-        call_params: dict[str, Any] = {
-            "model": self.model,
-            "messages": anthropic_messages,
-            "tools": anthropic_tools,
-            "max_tokens": max_completion_tokens or 4096,
-        }
-        if system_prompt:
-            call_params["system"] = system_prompt
-
-        if temperature is not None:
-            call_params["temperature"] = temperature
-
-        last_exception = None
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._client.messages.create(**call_params)
-
-                # Extract content and tool calls
-                content_parts = []
-                tool_calls: list[LLMToolCall] = []
-
-                for block in response.content:
-                    if block.type == "text":
-                        content_parts.append(block.text)
-                    elif block.type == "tool_use":
-                        tool_calls.append(LLMToolCall(id=block.id, name=block.name, arguments=block.input or {}))
-
-                content = "".join(content_parts) if content_parts else None
-                finish_reason = "tool_calls" if tool_calls else "stop"
-
-                # Extract token usage
-                input_tokens = response.usage.input_tokens or 0
-                output_tokens = response.usage.output_tokens or 0
-
-                # Record metrics
-                metrics = get_metrics_collector()
-                duration = time.time() - start_time
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                # Record OpenTelemetry span
-                from hindsight_api.tracing import get_span_recorder
-
-                span_recorder = get_span_recorder()
-                # Convert LLMToolCall objects to dicts for span recording
-                tool_calls_dict = (
-                    [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls]
-                    if tool_calls
-                    else None
-                )
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=content,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    duration=duration,
-                    finish_reason=finish_reason,
-                    error=None,
-                    tool_calls=tool_calls_dict,
-                )
-
-                return LLMToolCallResult(
-                    content=content,
-                    tool_calls=tool_calls,
-                    finish_reason=finish_reason,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                )
-
-            except (APIConnectionError, APIStatusError) as e:
-                if isinstance(e, APIStatusError) and e.status_code in (401, 403):
-                    raise
-                last_exception = e
-                if attempt < max_retries:
-                    await asyncio.sleep(min(initial_backoff * (2**attempt), max_backoff))
-                    continue
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Anthropic tool call failed")
-
-    async def cleanup(self) -> None:
-        """Clean up resources (close Anthropic client connections)."""
-        if hasattr(self, "_client") and self._client:
-            await self._client.close()
@@ -1,510 +0,0 @@
-"""
-Claude Code LLM provider using Claude Agent SDK.
-
-This provider enables using Claude Pro/Max subscriptions for API calls
-via the Claude CLI authentication. It uses the Claude Agent SDK which
-automatically handles authentication via `claude auth login` credentials.
-"""
-
-import asyncio
-import json
-import logging
-import time
-from typing import Any
-
-from hindsight_api.engine.llm_interface import LLMInterface, OutputTooLongError
-from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
-from hindsight_api.metrics import get_metrics_collector
-
-logger = logging.getLogger(__name__)
-
-
-class ClaudeCodeLLM(LLMInterface):
-    """
-    LLM provider using Claude Code authentication.
-
-    Authenticates using Claude Pro/Max credentials via `claude auth login`
-    and makes API calls through the Claude Agent SDK.
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,  # Will be ignored, uses CLI auth
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        **kwargs: Any,
-    ):
-        """Initialize Claude Code LLM provider."""
-        super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs)
-
-        # Verify Claude Agent SDK is available
-        try:
-            self._verify_claude_code_available()
-            logger.info("Claude Code: Using Claude Agent SDK (authentication via claude auth login)")
-        except Exception as e:
-            raise RuntimeError(
-                f"Failed to initialize Claude Code provider: {e}\n\n"
-                "To set up Claude Code authentication:\n"
-                "1. Install Claude Code CLI: npm install -g @anthropics/claude-code\n"
-                "2. Login with your Pro/Max plan: claude auth login\n"
-                "3. Verify authentication: claude --version\n\n"
-                "Or use a different provider (anthropic, openai, gemini) with API keys."
-            ) from e
-
-        # Metrics collector is imported at module level
-
-    def _verify_claude_code_available(self) -> None:
-        """
-        Verify that Claude Agent SDK can be imported and is properly configured.
-
-        Raises:
-            ImportError: If Claude Agent SDK is not installed.
-            RuntimeError: If Claude Code is not authenticated.
-        """
-        try:
-            # Import Claude Agent SDK
-            # Reduce Claude Agent SDK logging verbosity
-            import logging as sdk_logging
-
-            from claude_agent_sdk import query  # noqa: F401
-
-            sdk_logging.getLogger("claude_agent_sdk").setLevel(sdk_logging.WARNING)
-            sdk_logging.getLogger("claude_agent_sdk._internal").setLevel(sdk_logging.WARNING)
-
-            logger.debug("Claude Agent SDK imported successfully")
-        except ImportError as e:
-            raise ImportError(
-                "Claude Agent SDK not installed. Run: uv add claude-agent-sdk or pip install claude-agent-sdk"
-            ) from e
-
-        # SDK will automatically check for authentication when first used
-        # No need to verify here - let it fail gracefully on first call with helpful error
-
-    async def verify_connection(self) -> None:
-        """
-        Verify that the Claude Code provider is configured correctly by making a simple test call.
-
-        Raises:
-            RuntimeError: If the connection test fails.
-        """
-        try:
-            test_messages = [{"role": "user", "content": "test"}]
-            await self.call(
-                messages=test_messages,
-                max_completion_tokens=10,
-                temperature=0.0,
-                scope="verification",
-                max_retries=0,
-            )
-            logger.info("Claude Code connection verified successfully")
-        except Exception as e:
-            logger.error(f"Claude Code connection verification failed: {e}")
-            raise RuntimeError(f"Failed to verify Claude Code connection: {e}") from e
-
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Make an LLM API call with retry logic.
-
-        Args:
-            messages: List of message dicts with 'role' and 'content'.
-            response_format: Optional Pydantic model for structured output.
-            max_completion_tokens: Maximum tokens in response (ignored by Claude Agent SDK).
-            temperature: Sampling temperature (ignored by Claude Agent SDK).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            skip_validation: Return raw JSON without Pydantic validation.
-            strict_schema: Use strict JSON schema enforcement (not supported).
-            return_usage: If True, return tuple (result, TokenUsage) instead of just result.
-
-        Returns:
-            If return_usage=False: Parsed response if response_format is provided, otherwise text content.
-            If return_usage=True: Tuple of (result, TokenUsage) with estimated token counts.
-
-        Raises:
-            OutputTooLongError: If output exceeds token limits (not supported by Claude Agent SDK).
-            Exception: Re-raises API errors after retries exhausted.
-        """
-        from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, TextBlock, query
-
-        start_time = time.time()
-
-        # Build system prompt
-        system_prompt = ""
-        user_content = ""
-
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                system_prompt += ("\n\n" + content) if system_prompt else content
-            elif role == "user":
-                user_content += ("\n\n" + content) if user_content else content
-            elif role == "assistant":
-                # Claude Agent SDK doesn't support multi-turn easily in query()
-                # For now, prepend assistant messages to user content
-                user_content += f"\n\n[Previous assistant response: {content}]"
-
-        # Add JSON schema instruction if response_format is provided
-        if response_format is not None and hasattr(response_format, "model_json_schema"):
-            schema = response_format.model_json_schema()
-            schema_instruction = (
-                f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}\n\n"
-                "Respond with ONLY the JSON, no markdown formatting."
-            )
-            user_content += schema_instruction
-
-        # Configure SDK options
-        options = ClaudeAgentOptions(
-            system_prompt=system_prompt if system_prompt else None,
-            max_turns=1,  # Single-turn for API-style interactions
-            allowed_tools=[],  # Disable tools for standard LLM calls
-        )
-
-        # Call Claude Agent SDK
-        last_exception = None
-        for attempt in range(max_retries + 1):
-            try:
-                # Collect streaming response
-                full_text = ""
-
-                async for message in query(prompt=user_content, options=options):
-                    if isinstance(message, AssistantMessage):
-                        for block in message.content:
-                            if isinstance(block, TextBlock):
-                                full_text += block.text
-
-                # Handle structured output
-                if response_format is not None:
-                    # Models may wrap JSON in markdown
-                    clean_text = full_text
-                    if "```json" in full_text:
-                        clean_text = full_text.split("```json")[1].split("```")[0].strip()
-                    elif "```" in full_text:
-                        clean_text = full_text.split("```")[1].split("```")[0].strip()
-
-                    try:
-                        json_data = json.loads(clean_text)
-                    except json.JSONDecodeError as e:
-                        logger.warning(f"Claude Code JSON parse error (attempt {attempt + 1}/{max_retries + 1}): {e}")
-                        if attempt < max_retries:
-                            backoff = min(initial_backoff * (2**attempt), max_backoff)
-                            await asyncio.sleep(backoff)
-                            last_exception = e
-                            continue
-                        raise
-
-                    if skip_validation:
-                        result = json_data
-                    else:
-                        result = response_format.model_validate(json_data)
-                else:
-                    result = full_text
-
-                # Record metrics
-                duration = time.time() - start_time
-                metrics = get_metrics_collector()
-
-                # Estimate token usage (Claude Agent SDK doesn't report exact counts)
-                # Use character count / 4 as rough estimate (1 token ≈ 4 characters)
-                estimated_input = sum(len(m.get("content", "")) for m in messages) // 4
-                estimated_output = len(full_text) // 4
-
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=estimated_input,
-                    output_tokens=estimated_output,
-                    success=True,
-                )
-
-                # Record trace span
-                from hindsight_api.tracing import get_span_recorder
-
-                span_recorder = get_span_recorder()
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=result if isinstance(result, str) else json.dumps(result),
-                    input_tokens=estimated_input,
-                    output_tokens=estimated_output,
-                    duration=duration,
-                    finish_reason=None,
-                    error=None,
-                )
-
-                # Log slow calls
-                if duration > 10.0:
-                    logger.info(
-                        f"slow llm call: scope={scope}, model={self.provider}/{self.model}, time={duration:.3f}s"
-                    )
-
-                if return_usage:
-                    token_usage = TokenUsage(
-                        input_tokens=estimated_input,
-                        output_tokens=estimated_output,
-                        total_tokens=estimated_input + estimated_output,
-                    )
-                    return result, token_usage
-
-                return result
-
-            except Exception as e:
-                last_exception = e
-
-                # Check for authentication errors
-                error_str = str(e).lower()
-                if "auth" in error_str or "login" in error_str or "credential" in error_str:
-                    logger.error(f"Claude Code authentication error: {e}")
-                    raise RuntimeError(
-                        f"Claude Code authentication failed: {e}\n\n"
-                        "Run 'claude auth login' to authenticate with Claude Pro/Max."
-                    ) from e
-
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    logger.warning(f"Claude Code error (attempt {attempt + 1}/{max_retries + 1}): {e}")
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(f"Claude Code error after {max_retries + 1} attempts: {e}")
-                    raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Claude Code call failed after all retries")
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make an LLM API call with tool/function calling support using Claude Agent SDK.
-
-        This implementation uses ClaudeSDKClient (not query()) because custom tools via
-        SDK MCP servers are only supported with the client. Tools are converted from OpenAI
-        format to SDK MCP tools, and tool names are formatted as mcp__hindsight_tools__{name}.
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Maximum tokens in response (not used by Claude Agent SDK).
-            temperature: Sampling temperature (not used by Claude Agent SDK).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            tool_choice: How to choose tools (not used by Claude Agent SDK).
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        from claude_agent_sdk import (
-            AssistantMessage,
-            ClaudeAgentOptions,
-            ClaudeSDKClient,
-            SdkMcpTool,
-            TextBlock,
-            ToolUseBlock,
-            create_sdk_mcp_server,
-        )
-
-        start_time = time.time()
-
-        # Convert OpenAI tool format to Claude Agent SDK SdkMcpTool format
-        sdk_tools: list[SdkMcpTool] = []
-        tool_names: list[str] = []
-
-        for tool in tools:
-            func = tool.get("function", {})
-            tool_name = func.get("name", "")
-            tool_description = func.get("description", "")
-            parameters = func.get("parameters", {})
-
-            # Create a handler with proper closure to avoid transport issues
-            def make_handler(name: str):
-                async def handler(args: dict[str, Any]) -> dict[str, Any]:
-                    # Return immediately with success - tool execution happens externally
-                    return {
-                        "content": [
-                            {
-                                "type": "text",
-                                "text": f"[Tool {name} called successfully]",
-                            }
-                        ]
-                    }
-
-                return handler
-
-            sdk_tools.append(
-                SdkMcpTool(
-                    name=tool_name,
-                    description=tool_description,
-                    input_schema=parameters,
-                    handler=make_handler(tool_name),
-                )
-            )
-            tool_names.append(tool_name)
-
-        # Create an MCP server with the tools
-        mcp_server = create_sdk_mcp_server(
-            name="hindsight_tools",
-            version="1.0.0",
-            tools=sdk_tools if sdk_tools else None,
-        )
-
-        # Build system prompt and user content from messages
-        system_prompt = ""
-        user_content = ""
-
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                system_prompt += ("\n\n" + content) if system_prompt else content
-            elif role == "user":
-                user_content += ("\n\n" + content) if user_content else content
-            elif role == "assistant":
-                # Include previous assistant messages as context
-                user_content += f"\n\n[Previous assistant response: {content}]"
-            elif role == "tool":
-                # Tool results are already in tool_results_map, append to user context
-                tool_call_id = msg.get("tool_call_id", "")
-                user_content += f"\n\n[Tool result for {tool_call_id}: {content}]"
-
-        # Format tool names for SDK MCP servers: mcp__{server_name}__{tool_name}
-        # This is required by the Claude Agent SDK for MCP server tools
-        allowed_tool_names = [f"mcp__hindsight_tools__{name}" for name in tool_names]
-
-        # Configure SDK options with MCP server
-        options = ClaudeAgentOptions(
-            system_prompt=system_prompt if system_prompt else None,
-            max_turns=1,  # Single-turn for API-style interactions
-            mcp_servers={"hindsight_tools": mcp_server} if sdk_tools else {},
-            allowed_tools=allowed_tool_names if allowed_tool_names else [],
-        )
-
-        # Call Claude Agent SDK with retry logic
-        last_exception = None
-        for attempt in range(max_retries + 1):
-            try:
-                full_text = ""
-                tool_calls: list[LLMToolCall] = []
-
-                # Use ClaudeSDKClient for tool calling support
-                # Note: query() does NOT support custom tools, only ClaudeSDKClient does
-                async with ClaudeSDKClient(options=options) as client:
-                    # Send the query
-                    await client.query(user_content)
-
-                    # Receive response
-                    async for message in client.receive_response():
-                        if isinstance(message, AssistantMessage):
-                            for block in message.content:
-                                if isinstance(block, TextBlock):
-                                    full_text += block.text
-                                elif isinstance(block, ToolUseBlock):
-                                    # SDK returns tool names with MCP prefix (mcp__hindsight_tools__{name})
-                                    # Strip the prefix to return original tool name expected by caller
-                                    tool_name = block.name
-                                    if tool_name.startswith("mcp__hindsight_tools__"):
-                                        tool_name = tool_name.replace("mcp__hindsight_tools__", "", 1)
-
-                                    tool_calls.append(
-                                        LLMToolCall(
-                                            id=block.id,
-                                            name=tool_name,
-                                            arguments=block.input,
-                                        )
-                                    )
-
-                # Record metrics
-                duration = time.time() - start_time
-                metrics = get_metrics_collector()
-
-                # Estimate token usage (Claude Agent SDK doesn't report exact counts)
-                estimated_input = sum(len(m.get("content", "")) for m in messages) // 4
-                estimated_output = len(full_text) // 4
-
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=estimated_input,
-                    output_tokens=estimated_output,
-                    success=True,
-                )
-
-                # Log slow calls
-                if duration > 10.0:
-                    logger.info(
-                        f"slow llm call: scope={scope}, model={self.provider}/{self.model}, time={duration:.3f}s"
-                    )
-
-                return LLMToolCallResult(
-                    content=full_text if full_text else None,
-                    tool_calls=tool_calls,
-                    finish_reason="tool_calls" if tool_calls else "stop",
-                    input_tokens=estimated_input,
-                    output_tokens=estimated_output,
-                )
-
-            except Exception as e:
-                last_exception = e
-
-                # Check for authentication errors
-                error_str = str(e).lower()
-                if "auth" in error_str or "login" in error_str or "credential" in error_str:
-                    logger.error(f"Claude Code authentication error: {e}")
-                    raise RuntimeError(
-                        f"Claude Code authentication failed: {e}\n\n"
-                        "Run 'claude auth login' to authenticate with Claude Pro/Max."
-                    ) from e
-
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    logger.warning(f"Claude Code tool call error (attempt {attempt + 1}/{max_retries + 1}): {e}")
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(f"Claude Code tool call error after {max_retries + 1} attempts: {e}")
-                    raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Claude Code tool call failed after all retries")
-
-    async def cleanup(self) -> None:
-        """Clean up resources (no HTTP client to close for Claude Agent SDK)."""
-        pass
@@ -1,621 +0,0 @@
-"""
-OpenAI Codex LLM provider using ChatGPT Plus/Pro OAuth authentication.
-
-This provider enables using ChatGPT Plus/Pro subscriptions for API calls
-without separate OpenAI Platform API credits. It uses OAuth tokens from
-~/.codex/auth.json and communicates with the ChatGPT backend API.
-"""
-
-import asyncio
-import json
-import logging
-import os
-import time
-import uuid
-from pathlib import Path
-from typing import Any
-
-import httpx
-
-from hindsight_api.engine.llm_interface import LLMInterface, OutputTooLongError
-from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
-from hindsight_api.metrics import get_metrics_collector
-
-logger = logging.getLogger(__name__)
-
-
-class CodexLLM(LLMInterface):
-    """
-    LLM provider using OpenAI Codex OAuth authentication.
-
-    Authenticates using ChatGPT Plus/Pro credentials stored in ~/.codex/auth.json
-    and makes API calls to chatgpt.com/backend-api/codex/responses.
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,  # Will be ignored, reads from ~/.codex/auth.json
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        **kwargs: Any,
-    ):
-        """Initialize Codex LLM provider."""
-        super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs)
-
-        # Load Codex OAuth credentials
-        try:
-            self.access_token, self.account_id = self._load_codex_auth()
-            logger.info(f"Loaded Codex OAuth credentials for account: {self.account_id}")
-        except Exception as e:
-            raise RuntimeError(
-                f"Failed to load Codex OAuth credentials from ~/.codex/auth.json: {e}\n\n"
-                "To set up Codex authentication:\n"
-                "1. Install Codex CLI: npm install -g @openai/codex\n"
-                "2. Login: codex auth login\n"
-                "3. Verify: ls ~/.codex/auth.json\n\n"
-                "Or use a different provider (openai, anthropic, gemini) with API keys."
-            ) from e
-
-        # Use ChatGPT backend API endpoint
-        if not self.base_url:
-            self.base_url = "https://chatgpt.com/backend-api"
-
-        # Normalize model name (strip openai/ prefix if present)
-        if self.model.startswith("openai/"):
-            self.model = self.model[len("openai/") :]
-
-        # Map reasoning effort to Codex reasoning summary format
-        # Codex supports: "auto", "concise", "detailed"
-        self.reasoning_summary = self._map_reasoning_effort(reasoning_effort)
-
-        # HTTP client for SSE streaming
-        self._client = httpx.AsyncClient(timeout=120.0)
-
-    def _load_codex_auth(self) -> tuple[str, str]:
-        """
-        Load OAuth credentials from ~/.codex/auth.json.
-
-        Returns:
-            Tuple of (access_token, account_id).
-
-        Raises:
-            FileNotFoundError: If auth file doesn't exist.
-            ValueError: If auth file is invalid.
-        """
-        auth_file = Path.home() / ".codex" / "auth.json"
-
-        if not auth_file.exists():
-            raise FileNotFoundError(
-                f"Codex auth file not found: {auth_file}\nRun 'codex auth login' to authenticate with ChatGPT Plus/Pro."
-            )
-
-        with open(auth_file) as f:
-            data = json.load(f)
-
-        # Validate auth structure
-        auth_mode = data.get("auth_mode")
-        if auth_mode != "chatgpt":
-            raise ValueError(f"Expected auth_mode='chatgpt', got: {auth_mode}")
-
-        tokens = data.get("tokens", {})
-        access_token = tokens.get("access_token")
-        account_id = tokens.get("account_id")
-
-        if not access_token:
-            raise ValueError("No access_token found in Codex auth file. Run 'codex auth login' again.")
-
-        return access_token, account_id
-
-    def _map_reasoning_effort(self, effort: str) -> str:
-        """
-        Map standard reasoning effort to Codex reasoning summary format.
-
-        Args:
-            effort: Standard effort level ("low", "medium", "high", "xhigh").
-
-        Returns:
-            Codex reasoning summary: "concise", "detailed", or "auto".
-        """
-        mapping = {
-            "low": "concise",
-            "medium": "auto",
-            "high": "detailed",
-            "xhigh": "detailed",
-        }
-        return mapping.get(effort.lower(), "auto")
-
-    async def verify_connection(self) -> None:
-        """Verify Codex connection by making a simple test call."""
-        try:
-            logger.info(f"Verifying Codex LLM: model={self.model}, account={self.account_id}...")
-            await self.call(
-                messages=[{"role": "user", "content": "Say 'ok'"}],
-                max_completion_tokens=10,
-                max_retries=2,
-                initial_backoff=0.5,
-                max_backoff=2.0,
-                scope="verification",
-            )
-            logger.info(f"Codex LLM verified: {self.model}")
-        except Exception as e:
-            raise RuntimeError(f"Codex LLM connection verification failed for {self.model}: {e}") from e
-
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """Make API call to Codex backend with SSE streaming."""
-        start_time = time.time()
-
-        # Prepare system instructions
-        system_instruction = ""
-        user_messages = []
-
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                system_instruction += ("\n\n" + content) if system_instruction else content
-            else:
-                user_messages.append(msg)
-
-        # Add JSON schema instruction if response_format is provided
-        if response_format is not None and hasattr(response_format, "model_json_schema"):
-            schema = response_format.model_json_schema()
-            schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
-            system_instruction += schema_msg
-
-        # gpt-5.2-codex only supports "detailed" reasoning summary
-        reasoning_summary = "detailed" if "5.2" in self.model else self.reasoning_summary
-
-        # Build Codex request payload
-        payload = {
-            "model": self.model,
-            "instructions": system_instruction,
-            "input": [
-                {
-                    "type": "message",
-                    "role": msg.get("role", "user"),
-                    "content": msg.get("content", ""),
-                }
-                for msg in user_messages
-            ],
-            "tools": [],
-            "tool_choice": "auto",
-            "parallel_tool_calls": True,
-            "reasoning": {"summary": reasoning_summary},
-            "store": False,  # Codex uses stateless mode
-            "stream": True,  # SSE streaming
-            "include": ["reasoning.encrypted_content"],
-            "prompt_cache_key": str(uuid.uuid4()),
-        }
-
-        headers = {
-            "Authorization": f"Bearer {self.access_token}",
-            "Content-Type": "application/json",
-            "OpenAI-Account-ID": self.account_id,
-            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
-            "Origin": "https://chatgpt.com",
-        }
-
-        url = f"{self.base_url}/codex/responses"
-        last_exception = None
-
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._client.post(url, json=payload, headers=headers, timeout=120.0)
-                response.raise_for_status()
-
-                # Parse SSE stream
-                content = await self._parse_sse_stream(response)
-
-                # Handle structured output
-                if response_format is not None:
-                    # Models may wrap JSON in markdown
-                    clean_content = content
-                    if "```json" in content:
-                        clean_content = content.split("```json")[1].split("```")[0].strip()
-                    elif "```" in content:
-                        clean_content = content.split("```")[1].split("```")[0].strip()
-
-                    try:
-                        json_data = json.loads(clean_content)
-                    except json.JSONDecodeError as e:
-                        logger.warning(f"Codex JSON parse error (attempt {attempt + 1}/{max_retries + 1}): {e}")
-                        if attempt < max_retries:
-                            backoff = min(initial_backoff * (2**attempt), max_backoff)
-                            await asyncio.sleep(backoff)
-                            last_exception = e
-                            continue
-                        raise
-
-                    if skip_validation:
-                        result = json_data
-                    else:
-                        result = response_format.model_validate(json_data)
-                else:
-                    result = content
-
-                # Record metrics
-                duration = time.time() - start_time
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=0,  # Codex doesn't report token counts in SSE
-                    output_tokens=0,
-                    success=True,
-                )
-
-                # Record trace span
-                from hindsight_api.tracing import get_span_recorder
-
-                # Estimate tokens for tracing
-                estimated_input = sum(len(m.get("content", "")) for m in messages) // 4
-                estimated_output = len(content) // 4
-                span_recorder = get_span_recorder()
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=result if isinstance(result, str) else json.dumps(result),
-                    input_tokens=estimated_input,
-                    output_tokens=estimated_output,
-                    duration=duration,
-                    finish_reason=None,
-                    error=None,
-                )
-
-                if return_usage:
-                    # Codex doesn't provide token counts, estimate based on content
-                    estimated_input = sum(len(m.get("content", "")) for m in messages) // 4
-                    estimated_output = len(content) // 4
-                    token_usage = TokenUsage(
-                        input_tokens=estimated_input,
-                        output_tokens=estimated_output,
-                        total_tokens=estimated_input + estimated_output,
-                    )
-                    return result, token_usage
-
-                return result
-
-            except httpx.HTTPStatusError as e:
-                last_exception = e
-                status_code = e.response.status_code
-
-                # Fast fail on auth errors
-                if status_code in (401, 403):
-                    logger.error(f"Codex auth error (HTTP {status_code}): {e.response.text[:200]}")
-                    raise RuntimeError(
-                        "Codex authentication failed. Your OAuth token may have expired.\n"
-                        "Run 'codex auth login' to re-authenticate."
-                    ) from e
-
-                # Log the actual error message from the API
-                error_detail = e.response.text[:500] if hasattr(e.response, "text") else str(e)
-
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    logger.warning(
-                        f"Codex HTTP error {status_code} (attempt {attempt + 1}/{max_retries + 1}): {error_detail}"
-                    )
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(
-                        f"Codex HTTP error after {max_retries + 1} attempts: Status {status_code}, Detail: {error_detail}"
-                    )
-                    raise
-
-            except httpx.RequestError as e:
-                last_exception = e
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    logger.warning(f"Codex connection error (attempt {attempt + 1}/{max_retries + 1}): {e}")
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(f"Codex connection error after {max_retries + 1} attempts: {e}")
-                    raise
-
-            except Exception as e:
-                logger.error(f"Unexpected Codex error: {type(e).__name__}: {e}")
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Codex call failed after all retries")
-
-    async def _parse_sse_stream(self, response: httpx.Response) -> str:
-        """
-        Parse Server-Sent Events (SSE) stream from Codex API.
-
-        Args:
-            response: HTTP response with SSE stream.
-
-        Returns:
-            Extracted text content from stream.
-        """
-        full_text = ""
-        event_type = None
-
-        async for line in response.aiter_lines():
-            if not line:
-                continue
-
-            # Track event type
-            if line.startswith("event: "):
-                event_type = line[7:]
-
-            # Parse data
-            elif line.startswith("data: "):
-                data_str = line[6:]
-                if data_str == "[DONE]":
-                    break
-
-                try:
-                    data = json.loads(data_str)
-
-                    # Extract content based on event type
-                    if event_type == "response.text.delta" and "delta" in data:
-                        full_text += data["delta"]
-                    elif event_type == "response.content_part.delta" and "delta" in data:
-                        full_text += data["delta"]
-                    # Check for item content
-                    elif "item" in data:
-                        item = data["item"]
-                        if "content" in item:
-                            content = item["content"]
-                            if isinstance(content, list):
-                                for part in content:
-                                    if isinstance(part, dict) and "text" in part:
-                                        full_text += part["text"]
-                            elif isinstance(content, str):
-                                full_text += content
-
-                except json.JSONDecodeError:
-                    # Skip malformed JSON events
-                    pass
-
-        return full_text
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make API call with tool calling support.
-
-        Parses Codex SSE stream to extract tool calls from response.output_item.done events.
-        Tools are converted from OpenAI format to Codex format (flat structure at top level).
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature.
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            tool_choice: How to choose tools - "auto", "none", "required", or specific function.
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        start_time = time.time()
-
-        # Prepare system instructions
-        system_instruction = ""
-        user_messages = []
-
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                system_instruction += ("\n\n" + content) if system_instruction else content
-            elif role == "tool":
-                # Handle tool results
-                user_messages.append(
-                    {
-                        "type": "message",
-                        "role": "user",
-                        "content": f"Tool result: {content}",
-                    }
-                )
-            else:
-                user_messages.append(
-                    {
-                        "type": "message",
-                        "role": role,
-                        "content": content,
-                    }
-                )
-
-        # Convert tools to Codex format
-        # Codex expects tools with type and name/description/parameters at top level
-        codex_tools = []
-        for tool in tools:
-            func = tool.get("function", {})
-            codex_tools.append(
-                {
-                    "type": "function",
-                    "name": func.get("name", ""),
-                    "description": func.get("description", ""),
-                    "parameters": func.get("parameters", {}),
-                }
-            )
-
-        # gpt-5.2-codex only supports "detailed" reasoning summary
-        reasoning_summary = "detailed" if "5.2" in self.model else self.reasoning_summary
-
-        payload = {
-            "model": self.model,
-            "instructions": system_instruction,
-            "input": user_messages,
-            "tools": codex_tools,
-            "tool_choice": tool_choice,
-            "parallel_tool_calls": True,
-            "reasoning": {"summary": reasoning_summary},
-            "store": False,
-            "stream": True,
-            "include": ["reasoning.encrypted_content"],
-            "prompt_cache_key": str(uuid.uuid4()),
-        }
-
-        headers = {
-            "Authorization": f"Bearer {self.access_token}",
-            "Content-Type": "application/json",
-            "OpenAI-Account-ID": self.account_id,
-            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
-            "Origin": "https://chatgpt.com",
-        }
-
-        url = f"{self.base_url}/codex/responses"
-
-        # Debug logging for troubleshooting
-        logger.debug(f"Codex tool call request: url={url}, model={payload['model']}, tools={len(codex_tools)}")
-
-        try:
-            response = await self._client.post(url, json=payload, headers=headers, timeout=120.0)
-
-            # Log response details on error
-            if response.status_code != 200:
-                logger.error(f"Codex API error {response.status_code}: {response.text[:500]}")
-
-            response.raise_for_status()
-
-            # Parse SSE for tool calls and content
-            content, tool_calls = await self._parse_sse_tool_stream(response)
-
-            duration = time.time() - start_time
-            metrics = get_metrics_collector()
-            metrics.record_llm_call(
-                provider=self.provider,
-                model=self.model,
-                scope=scope,
-                duration=duration,
-                input_tokens=0,
-                output_tokens=0,
-                success=True,
-            )
-
-            # Record OpenTelemetry span
-            from hindsight_api.tracing import get_span_recorder
-
-            span_recorder = get_span_recorder()
-            # Convert LLMToolCall objects to dicts for span recording
-            tool_calls_dict = (
-                [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls] if tool_calls else None
-            )
-            span_recorder.record_llm_call(
-                provider=self.provider,
-                model=self.model,
-                scope=scope,
-                messages=messages,
-                response_content=content,
-                input_tokens=0,  # Codex doesn't provide token counts
-                output_tokens=0,
-                duration=duration,
-                finish_reason="tool_calls" if tool_calls else "stop",
-                error=None,
-                tool_calls=tool_calls_dict,
-            )
-
-            return LLMToolCallResult(
-                content=content,
-                tool_calls=tool_calls,
-                finish_reason="tool_calls" if tool_calls else "stop",
-                input_tokens=0,
-                output_tokens=0,
-            )
-
-        except Exception as e:
-            logger.error(f"Codex tool call error: {e}")
-            raise
-
-    async def _parse_sse_tool_stream(self, response: httpx.Response) -> tuple[str | None, list[LLMToolCall]]:
-        """
-        Parse SSE stream for tool calls and content.
-
-        Returns:
-            Tuple of (content, tool_calls).
-        """
-        content = ""
-        tool_calls: list[LLMToolCall] = []
-        event_type = None
-
-        async for line in response.aiter_lines():
-            if not line:
-                continue
-
-            if line.startswith("event: "):
-                event_type = line[7:]
-
-            elif line.startswith("data: "):
-                data_str = line[6:]
-                if data_str == "[DONE]":
-                    break
-
-                try:
-                    data = json.loads(data_str)
-
-                    # Extract text content
-                    if event_type == "response.text.delta" and "delta" in data:
-                        content += data["delta"]
-
-                    # Extract completed tool calls from response.output_item.done
-                    elif event_type == "response.output_item.done":
-                        item = data.get("item", {})
-                        if item.get("type") == "function_call" and item.get("status") == "completed":
-                            tool_name = item.get("name", "")
-                            arguments_str = item.get("arguments", "{}")
-                            call_id = item.get("call_id", "")
-
-                            try:
-                                arguments = json.loads(arguments_str)
-                            except json.JSONDecodeError:
-                                logger.warning(f"Failed to parse tool arguments: {arguments_str}")
-                                arguments = {}
-
-                            tool_calls.append(
-                                LLMToolCall(
-                                    id=call_id,
-                                    name=tool_name,
-                                    arguments=arguments,
-                                )
-                            )
-
-                except json.JSONDecodeError as e:
-                    logger.warning(f"Failed to parse SSE data: {e}, data_str: {data_str[:200]}")
-
-        return content if content else None, tool_calls
-
-    async def cleanup(self) -> None:
-        """Clean up HTTP client."""
-        await self._client.aclose()
@@ -1,550 +0,0 @@
-"""
-Google Gemini/VertexAI LLM provider.
-
-This provider supports both:
-1. Gemini API (api.generativeai.google.com) with API key authentication
-2. Vertex AI with service account or Application Default Credentials (ADC)
-"""
-
-import asyncio
-import json
-import logging
-import os
-import time
-from typing import Any
-
-from google import genai
-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.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
-from hindsight_api.metrics import get_metrics_collector
-
-logger = logging.getLogger(__name__)
-
-# Vertex AI imports (optional)
-try:
-    import google.auth
-    from google.oauth2 import service_account
-
-    VERTEXAI_AVAILABLE = True
-except ImportError:
-    VERTEXAI_AVAILABLE = False
-
-
-class GeminiLLM(LLMInterface):
-    """
-    LLM provider for Google Gemini and Vertex AI.
-
-    Supports:
-    - Gemini API: provider="gemini", requires api_key
-    - Vertex AI: provider="vertexai", requires project_id and region, uses ADC or service account
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        **kwargs: Any,
-    ):
-        """Initialize Gemini/VertexAI LLM provider."""
-        super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs)
-
-        self._client = None
-        self._is_vertexai = self.provider == "vertexai"
-
-        if self._is_vertexai:
-            self._init_vertexai(**kwargs)
-        else:
-            self._init_gemini()
-
-    def _init_gemini(self) -> None:
-        """Initialize Gemini API client."""
-        if not self.api_key:
-            raise ValueError("Gemini provider requires api_key")
-
-        self._client = genai.Client(api_key=self.api_key)
-        logger.info(f"Gemini API: model={self.model}")
-
-    def _init_vertexai(self, **kwargs: Any) -> None:
-        """Initialize Vertex AI client with project, region, and credentials."""
-        # Extract Vertex AI config from kwargs
-        project_id = kwargs.get("vertexai_project_id")
-        region = kwargs.get("vertexai_region", "us-central1")
-        service_account_key = kwargs.get("vertexai_service_account_key")
-        credentials = kwargs.get("vertexai_credentials")  # Pre-loaded credentials object
-
-        if not project_id:
-            raise ValueError(
-                "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID is required for Vertex AI provider. "
-                "Set it to your GCP project ID."
-            )
-
-        auth_method = "ADC"
-
-        # Use pre-loaded credentials if provided (passed from LLMProvider)
-        if credentials is not None:
-            auth_method = "service_account"
-        # Otherwise, load explicit service account credentials if path provided
-        elif service_account_key:
-            if not VERTEXAI_AVAILABLE:
-                raise ValueError(
-                    "Vertex AI service account auth requires 'google-auth' package. "
-                    "Install with: pip install google-auth"
-                )
-            credentials = service_account.Credentials.from_service_account_file(
-                service_account_key,
-                scopes=["https://www.googleapis.com/auth/cloud-platform"],
-            )
-            auth_method = "service_account"
-            logger.info(f"Vertex AI: Using service account key: {service_account_key}")
-
-        # Strip google/ prefix from model name — native SDK uses bare names
-        # e.g. "google/gemini-2.0-flash-lite-001" -> "gemini-2.0-flash-lite-001"
-        if self.model.startswith("google/"):
-            self.model = self.model[len("google/") :]
-
-        # Create Vertex AI client
-        client_kwargs: dict[str, Any] = {
-            "vertexai": True,
-            "project": project_id,
-            "location": region,
-        }
-        if credentials is not None:
-            client_kwargs["credentials"] = credentials
-
-        self._client = genai.Client(**client_kwargs)
-
-        logger.info(f"Vertex AI: project={project_id}, region={region}, model={self.model}, auth={auth_method}")
-
-    async def verify_connection(self) -> None:
-        """
-        Verify that the Gemini/VertexAI provider is configured correctly.
-
-        Raises:
-            RuntimeError: If the connection test fails.
-        """
-        try:
-            logger.info(f"Verifying {self.provider.upper()}: model={self.model}...")
-            await self.call(
-                messages=[{"role": "user", "content": "Say 'ok'"}],
-                max_completion_tokens=100,
-                max_retries=2,
-                initial_backoff=0.5,
-                max_backoff=2.0,
-                scope="verification",
-            )
-            logger.info(f"{self.provider.upper()} connection verified successfully")
-        except Exception as e:
-            raise RuntimeError(f"Failed to verify {self.provider.upper()} connection: {e}") from e
-
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Make a Gemini/VertexAI API call with retry logic.
-
-        Args:
-            messages: List of message dicts with 'role' and 'content'.
-            response_format: Optional Pydantic model for structured output.
-            max_completion_tokens: Maximum tokens in response (not supported by Gemini).
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            skip_validation: Return raw JSON without Pydantic validation.
-            strict_schema: Use strict JSON schema enforcement (not supported by Gemini).
-            return_usage: If True, return tuple (result, TokenUsage).
-
-        Returns:
-            If return_usage=False: Parsed response if response_format provided, else text.
-            If return_usage=True: Tuple of (result, TokenUsage).
-        """
-        start_time = time.time()
-
-        # Convert OpenAI-style messages to Gemini format
-        system_instruction = None
-        gemini_contents = []
-
-        for msg in messages:
-            role = msg.get("role", "user")
-            content = msg.get("content", "")
-
-            if role == "system":
-                if system_instruction:
-                    system_instruction += "\n\n" + content
-                else:
-                    system_instruction = content
-            elif role == "assistant":
-                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)]))
-
-        # Add JSON schema instruction if response_format is provided
-        if response_format is not None and hasattr(response_format, "model_json_schema"):
-            schema = response_format.model_json_schema()
-            schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
-            if system_instruction:
-                system_instruction += schema_msg
-            else:
-                system_instruction = schema_msg
-
-        # Build generation config
-        config_kwargs: dict[str, Any] = {}
-        if system_instruction:
-            config_kwargs["system_instruction"] = system_instruction
-        if response_format is not None:
-            config_kwargs["response_mime_type"] = "application/json"
-            config_kwargs["response_schema"] = response_format
-        if temperature is not None:
-            config_kwargs["temperature"] = temperature
-
-        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 self._client.aio.models.generate_content(
-                    model=self.model,
-                    contents=gemini_contents,
-                    config=generation_config,
-                )
-
-                content = response.text
-
-                # Handle empty response
-                if content is None:
-                    block_reason = None
-                    if hasattr(response, "candidates") and response.candidates:
-                        candidate = response.candidates[0]
-                        if hasattr(candidate, "finish_reason"):
-                            block_reason = candidate.finish_reason
-
-                    if attempt < max_retries:
-                        logger.warning(f"Gemini returned empty response (reason: {block_reason}), retrying...")
-                        backoff = min(initial_backoff * (2**attempt), max_backoff)
-                        await asyncio.sleep(backoff)
-                        continue
-                    else:
-                        raise RuntimeError(f"Gemini returned empty response after {max_retries + 1} attempts")
-
-                # Parse structured output if requested
-                if response_format is not None:
-                    json_data = json.loads(content)
-                    if skip_validation:
-                        result = json_data
-                    else:
-                        result = response_format.model_validate(json_data)
-                else:
-                    result = content
-
-                # Extract token usage
-                input_tokens = 0
-                output_tokens = 0
-                if hasattr(response, "usage_metadata") and response.usage_metadata:
-                    usage = response.usage_metadata
-                    input_tokens = usage.prompt_token_count or 0
-                    output_tokens = usage.candidates_token_count or 0
-
-                # Record metrics
-                duration = time.time() - start_time
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                # Record trace span
-                from hindsight_api.tracing import get_span_recorder
-
-                finish_reason = None
-                if hasattr(response, "candidates") and response.candidates:
-                    if hasattr(response.candidates[0], "finish_reason"):
-                        finish_reason = str(response.candidates[0].finish_reason)
-                span_recorder = get_span_recorder()
-                from hindsight_api.tracing import _serialize_for_span
-
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=_serialize_for_span(result),
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    duration=duration,
-                    finish_reason=finish_reason,
-                    error=None,
-                )
-
-                # Log slow calls
-                if duration > 10.0 and input_tokens > 0:
-                    logger.info(
-                        f"slow llm call: scope={scope}, model={self.provider}/{self.model}, "
-                        f"input_tokens={input_tokens}, output_tokens={output_tokens}, "
-                        f"time={duration:.3f}s"
-                    )
-
-                if return_usage:
-                    token_usage = TokenUsage(
-                        input_tokens=input_tokens,
-                        output_tokens=output_tokens,
-                        total_tokens=input_tokens + output_tokens,
-                    )
-                    return result, token_usage
-                return result
-
-            except json.JSONDecodeError as e:
-                last_exception = e
-                if attempt < max_retries:
-                    logger.warning("Gemini returned invalid JSON, retrying...")
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(f"Gemini returned invalid JSON after {max_retries + 1} attempts")
-                    raise
-
-            except genai_errors.APIError as e:
-                # Fast fail on auth errors - these won't recover with retries
-                if e.code in (401, 403):
-                    logger.error(f"Gemini auth error (HTTP {e.code}), not retrying: {str(e)}")
-                    raise
-
-                # Retry on retryable errors (rate limits, server errors, client errors)
-                if e.code in (400, 429, 500, 502, 503, 504) or (e.code and e.code >= 500):
-                    last_exception = e
-                    if attempt < max_retries:
-                        backoff = min(initial_backoff * (2**attempt), max_backoff)
-                        jitter = backoff * 0.2 * (2 * (time.time() % 1) - 1)
-                        await asyncio.sleep(backoff + jitter)
-                    else:
-                        logger.error(f"Gemini API error after {max_retries + 1} attempts: {str(e)}")
-                        raise
-                else:
-                    logger.error(f"Gemini API error: {type(e).__name__}: {str(e)}")
-                    raise
-
-            except Exception as e:
-                logger.error(f"Unexpected error during Gemini call: {type(e).__name__}: {str(e)}")
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Gemini call failed after all retries")
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make a Gemini/VertexAI API call with tool/function calling support.
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Maximum tokens (not supported by Gemini).
-            temperature: Sampling temperature.
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            tool_choice: How to choose tools (Gemini uses "auto" only).
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        start_time = time.time()
-
-        # Convert tools to Gemini format
-        gemini_tools = []
-        for tool in tools:
-            func = tool.get("function", {})
-            gemini_tools.append(
-                genai_types.Tool(
-                    function_declarations=[
-                        genai_types.FunctionDeclaration(
-                            name=func.get("name", ""),
-                            description=func.get("description", ""),
-                            parameters=func.get("parameters"),
-                        )
-                    ]
-                )
-            )
-
-        # Convert messages
-        system_instruction = None
-        gemini_contents = []
-        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
-            elif role == "tool":
-                # 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},
-                                )
-                            )
-                        ],
-                    )
-                )
-            elif role == "assistant":
-                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)]))
-
-        config_kwargs: dict[str, Any] = {"tools": gemini_tools}
-        if system_instruction:
-            config_kwargs["system_instruction"] = system_instruction
-        if temperature is not None:
-            config_kwargs["temperature"] = temperature
-
-        config = genai_types.GenerateContentConfig(**config_kwargs)
-
-        last_exception = None
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._client.aio.models.generate_content(
-                    model=self.model,
-                    contents=gemini_contents,
-                    config=config,
-                )
-
-                # Extract content and tool calls
-                content = None
-                tool_calls: list[LLMToolCall] = []
-
-                if response.candidates and response.candidates[0].content:
-                    parts = response.candidates[0].content.parts
-                    if parts:
-                        for part in parts:
-                            if hasattr(part, "text") and part.text:
-                                content = part.text
-                            if hasattr(part, "function_call") and part.function_call:
-                                fc = part.function_call
-                                tool_calls.append(
-                                    LLMToolCall(
-                                        id=f"gemini_{len(tool_calls)}",
-                                        name=fc.name,
-                                        arguments=dict(fc.args) if fc.args else {},
-                                    )
-                                )
-
-                finish_reason = "tool_calls" if tool_calls else "stop"
-
-                # Extract token usage
-                input_tokens = 0
-                output_tokens = 0
-                if response.usage_metadata:
-                    input_tokens = response.usage_metadata.prompt_token_count or 0
-                    output_tokens = response.usage_metadata.candidates_token_count or 0
-
-                # Record metrics
-                duration = time.time() - start_time
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                # Record OpenTelemetry span
-                from hindsight_api.tracing import get_span_recorder
-
-                span_recorder = get_span_recorder()
-                # Convert LLMToolCall objects to dicts for span recording
-                tool_calls_dict = (
-                    [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls]
-                    if tool_calls
-                    else None
-                )
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=content,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    duration=duration,
-                    finish_reason=finish_reason,
-                    error=None,
-                    tool_calls=tool_calls_dict,
-                )
-
-                return LLMToolCallResult(
-                    content=content,
-                    tool_calls=tool_calls,
-                    finish_reason=finish_reason,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                )
-
-            except genai_errors.APIError as e:
-                # Fast fail on auth errors
-                if e.code in (401, 403):
-                    logger.error(f"Gemini auth error (HTTP {e.code}), not retrying: {str(e)}")
-                    raise
-
-                # Retry on retryable errors
-                last_exception = e
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    await asyncio.sleep(backoff)
-                    continue
-                raise
-
-            except Exception as e:
-                logger.error(f"Unexpected error during Gemini tool call: {type(e).__name__}: {str(e)}")
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Gemini tool call failed")
-
-    async def cleanup(self) -> None:
-        """Clean up resources (close connections, etc.)."""
-        # Gemini client doesn't require explicit cleanup
-        pass
@@ -1,301 +0,0 @@
-"""
-Mock LLM provider for testing.
-
-This provider allows tests to record LLM calls and return configurable mock responses
-without making actual API calls to external LLM services.
-"""
-
-import logging
-from typing import Any
-
-from ..llm_interface import LLMInterface
-from ..response_models import LLMToolCall, LLMToolCallResult, TokenUsage
-
-logger = logging.getLogger(__name__)
-
-
-class MockLLM(LLMInterface):
-    """
-    Mock LLM provider for testing.
-
-    This provider records all calls and returns configurable mock responses,
-    enabling tests to verify LLM interactions without making real API calls.
-
-    Example:
-        # Create mock provider
-        mock_llm = MockLLM(provider="mock", api_key="", base_url="", model="mock-model")
-
-        # Set mock response
-        mock_llm.set_mock_response({"answer": "test"})
-
-        # Make calls
-        result = await mock_llm.call(
-            messages=[{"role": "user", "content": "test"}],
-            response_format=MyResponseModel
-        )
-
-        # Verify calls
-        calls = mock_llm.get_mock_calls()
-        assert len(calls) == 1
-        assert calls[0]["scope"] == "memory"
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        **kwargs: Any,
-    ):
-        """
-        Initialize mock LLM provider.
-
-        Args:
-            provider: Provider name (should be "mock").
-            api_key: Not used for mock provider.
-            base_url: Not used for mock provider.
-            model: Model name for tracking.
-            reasoning_effort: Not used for mock provider.
-            **kwargs: Additional parameters (not used).
-        """
-        super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs)
-
-        # Storage for test verification
-        self._mock_calls: list[dict] = []
-        self._mock_response: Any = None
-        self._mock_exception: Exception | None = None
-
-    async def verify_connection(self) -> None:
-        """
-        Verify mock provider (always succeeds).
-
-        Mock provider doesn't need connection verification since it doesn't
-        make real API calls.
-        """
-        logger.debug("Mock LLM: connection verification (always succeeds)")
-
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Make a mock LLM API call.
-
-        Records the call for test verification and returns the configured mock response.
-
-        Args:
-            messages: List of message dicts with 'role' and 'content'.
-            response_format: Optional Pydantic model for structured output.
-            max_completion_tokens: Not used in mock.
-            temperature: Not used in mock.
-            scope: Scope identifier for tracking.
-            max_retries: Not used in mock.
-            initial_backoff: Not used in mock.
-            max_backoff: Not used in mock.
-            skip_validation: Return raw JSON without Pydantic validation.
-            strict_schema: Not used in mock.
-            return_usage: If True, return tuple (result, TokenUsage) instead of just result.
-
-        Returns:
-            If return_usage=False: Parsed response if response_format is provided, otherwise text content.
-            If return_usage=True: Tuple of (result, TokenUsage) with mock token counts.
-        """
-        # Record the call for test verification
-        call_record = {
-            "provider": self.provider,
-            "model": self.model,
-            "messages": messages,
-            "response_format": response_format.__name__
-            if response_format and hasattr(response_format, "__name__")
-            else str(response_format),
-            "scope": scope,
-        }
-        self._mock_calls.append(call_record)
-        logger.debug(f"Mock LLM call recorded: scope={scope}, model={self.model}")
-
-        # Raise mock exception if configured
-        if self._mock_exception is not None:
-            raise self._mock_exception
-
-        # Record trace span (minimal for mock provider)
-        from hindsight_api.tracing import get_span_recorder
-
-        span_recorder = get_span_recorder()
-        span_recorder.record_llm_call(
-            provider=self.provider,
-            model=self.model,
-            scope=scope,
-            messages=messages,
-            response_content="mock response",
-            input_tokens=10,
-            output_tokens=5,
-            duration=0.001,  # Mock calls are instant
-            finish_reason="stop",
-            error=None,
-        )
-
-        # Return mock response
-        if self._mock_response is not None:
-            result = self._mock_response
-        elif response_format is not None:
-            # Try to create a minimal valid instance of the response format
-            try:
-                # For Pydantic models, try to create with minimal valid data
-                result = {"mock": True}
-            except Exception:
-                result = {"mock": True}
-        else:
-            result = "mock response"
-
-        if return_usage:
-            token_usage = TokenUsage(input_tokens=10, output_tokens=5, total_tokens=15)
-            return result, token_usage
-        return result
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make a mock LLM API call with tool/function calling support.
-
-        Records the call for test verification and returns the configured mock response.
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Not used in mock.
-            temperature: Not used in mock.
-            scope: Scope identifier for tracking.
-            max_retries: Not used in mock.
-            initial_backoff: Not used in mock.
-            max_backoff: Not used in mock.
-            tool_choice: Not used in mock.
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        # Record the call for test verification
-        call_record = {
-            "provider": self.provider,
-            "model": self.model,
-            "messages": messages,
-            "tools": [t.get("function", {}).get("name") for t in tools],
-            "scope": scope,
-        }
-        self._mock_calls.append(call_record)
-
-        # Raise mock exception if configured
-        if self._mock_exception is not None:
-            raise self._mock_exception
-
-        # Record OpenTelemetry span
-        from hindsight_api.tracing import get_span_recorder
-
-        span_recorder = get_span_recorder()
-
-        if self._mock_response is not None:
-            if isinstance(self._mock_response, LLMToolCallResult):
-                result = self._mock_response
-            elif isinstance(self._mock_response, list):
-                # Allow setting just tool calls as a list
-                result = LLMToolCallResult(
-                    tool_calls=[
-                        LLMToolCall(id=f"mock_{i}", name=tc["name"], arguments=tc.get("arguments", {}))
-                        for i, tc in enumerate(self._mock_response)
-                    ],
-                    finish_reason="tool_calls",
-                )
-            else:
-                result = LLMToolCallResult(content="mock response", finish_reason="stop")
-        else:
-            result = LLMToolCallResult(content="mock response", finish_reason="stop")
-
-        # Record span with mock values
-        # Convert LLMToolCall objects to dicts for span recording
-        tool_calls_dict = (
-            [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in result.tool_calls]
-            if result.tool_calls
-            else None
-        )
-        span_recorder.record_llm_call(
-            provider=self.provider,
-            model=self.model,
-            scope=scope,
-            messages=messages,
-            response_content=result.content,
-            input_tokens=10,  # Mock value
-            output_tokens=5,  # Mock value
-            duration=0.1,  # Mock value
-            finish_reason=result.finish_reason,
-            error=None,
-            tool_calls=tool_calls_dict,
-        )
-
-        return result
-
-    async def cleanup(self) -> None:
-        """Clean up resources (no-op for mock provider)."""
-        pass
-
-    def set_mock_response(self, response: Any) -> None:
-        """
-        Set the response to return from mock calls.
-
-        Args:
-            response: The response to return. Can be:
-                - A dict/Pydantic model for regular calls
-                - An LLMToolCallResult for tool calls
-                - A list of tool call dicts for tool calls
-                - Any other value to return as-is
-        """
-        self._mock_response = response
-
-    def set_mock_exception(self, exception: Exception) -> None:
-        """
-        Set an exception to raise from mock calls.
-
-        Args:
-            exception: The exception to raise on the next call.
-                      After raising, the exception is cleared.
-        """
-        self._mock_exception = exception
-
-    def get_mock_calls(self) -> list[dict]:
-        """
-        Get the list of recorded mock calls.
-
-        Returns:
-            List of call records, each containing:
-                - provider: Provider name
-                - model: Model name
-                - messages: Messages sent
-                - response_format/tools: Format or tools used
-                - scope: Call scope
-        """
-        return self._mock_calls
-
-    def clear_mock_calls(self) -> None:
-        """Clear the recorded mock calls and any set exception."""
-        self._mock_calls = []
-        self._mock_exception = None
@@ -1,788 +0,0 @@
-"""
-OpenAI-compatible LLM provider supporting OpenAI, Groq, Ollama, and LMStudio.
-
-This provider handles all OpenAI API-compatible models including:
- OpenAI: GPT-4, GPT-4o, GPT-5, o1, o3 (reasoning models)
- Groq: Fast inference with seed control and service tiers
- Ollama: Local models with native streaming API support
- LMStudio: Local models with OpenAI-compatible API
-
-Features:
- Reasoning models with extended thinking (o1, o3, GPT-5 families)
- Strict JSON schema enforcement (OpenAI)
- Provider-specific parameters (Groq seed, service tier)
- Native Ollama streaming for better structured output
- Automatic token limit handling per model family
-"""
-
-import asyncio
-import json
-import logging
-import os
-import re
-import time
-from typing import Any
-
-import httpx
-from openai import APIConnectionError, APIStatusError, AsyncOpenAI, LengthFinishReasonError
-
-from hindsight_api.config import DEFAULT_LLM_TIMEOUT, ENV_LLM_TIMEOUT
-from hindsight_api.engine.llm_interface import LLMInterface, OutputTooLongError
-from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
-from hindsight_api.metrics import get_metrics_collector
-
-logger = logging.getLogger(__name__)
-
-# Seed applied to every Groq request for deterministic behavior
-DEFAULT_LLM_SEED = 4242
-
-
-class OpenAICompatibleLLM(LLMInterface):
-    """
-    LLM provider for OpenAI-compatible APIs.
-
-    Supports:
-    - OpenAI: Standard models (GPT-4, GPT-4o) and reasoning models (o1, o3, GPT-5)
-    - Groq: Fast inference with seed control and service tiers
-    - Ollama: Local models with native streaming API for better structured output
-    - LMStudio: Local models with OpenAI-compatible API
-    """
-
-    def __init__(
-        self,
-        provider: str,
-        api_key: str,
-        base_url: str,
-        model: str,
-        reasoning_effort: str = "low",
-        timeout: float | None = None,
-        groq_service_tier: str | None = None,
-        **kwargs: Any,
-    ):
-        """
-        Initialize OpenAI-compatible LLM provider.
-
-        Args:
-            provider: Provider name ("openai", "groq", "ollama", "lmstudio").
-            api_key: API key (optional for ollama/lmstudio).
-            base_url: Base URL for the API (uses defaults for groq/ollama/lmstudio if empty).
-            model: Model name.
-            reasoning_effort: Reasoning effort level for supported models ("low", "medium", "high").
-            timeout: Request timeout in seconds (uses env var or 300s default).
-            groq_service_tier: Groq service tier ("on_demand", "flex", "auto").
-            **kwargs: Additional provider-specific parameters.
-        """
-        super().__init__(provider, api_key, base_url, model, reasoning_effort, **kwargs)
-
-        # Validate provider
-        valid_providers = ["openai", "groq", "ollama", "lmstudio"]
-        if self.provider not in valid_providers:
-            raise ValueError(f"OpenAICompatibleLLM only supports: {', '.join(valid_providers)}. Got: {self.provider}")
-
-        # Set default base URLs
-        if not self.base_url:
-            if self.provider == "groq":
-                self.base_url = "https://api.groq.com/openai/v1"
-            elif self.provider == "ollama":
-                self.base_url = "http://localhost:11434/v1"
-            elif self.provider == "lmstudio":
-                self.base_url = "http://localhost:1234/v1"
-
-        # For ollama/lmstudio, use dummy key if not provided
-        if self.provider in ("ollama", "lmstudio") and not self.api_key:
-            self.api_key = "local"
-
-        # Validate API key for cloud providers
-        if self.provider in ("openai", "groq") and not self.api_key:
-            raise ValueError(f"API key is required for {self.provider}")
-
-        # 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)))
-
-        # Create OpenAI client
-        client_kwargs: dict[str, Any] = {"api_key": self.api_key, "max_retries": 0}
-        if self.base_url:
-            client_kwargs["base_url"] = self.base_url
-        if self.timeout:
-            client_kwargs["timeout"] = self.timeout
-
-        self._client = AsyncOpenAI(**client_kwargs)
-        logger.info(
-            f"OpenAI-compatible client initialized: provider={self.provider}, model={self.model}, "
-            f"base_url={self.base_url or 'default'}"
-        )
-
-    async def verify_connection(self) -> None:
-        """
-        Verify that the provider is configured correctly by making a simple test call.
-
-        Raises:
-            RuntimeError: If the connection test fails.
-        """
-        try:
-            logger.info(f"Verifying connection: {self.provider}/{self.model}")
-            await self.call(
-                messages=[{"role": "user", "content": "Say 'ok'"}],
-                max_completion_tokens=100,
-                max_retries=2,
-                initial_backoff=0.5,
-                max_backoff=2.0,
-                scope="verification",
-            )
-            logger.info(f"Connection verified: {self.provider}/{self.model}")
-        except Exception as e:
-            raise RuntimeError(f"Connection verification failed for {self.provider}/{self.model}: {e}") from e
-
-    def _supports_reasoning_model(self) -> bool:
-        """Check if the current model is a reasoning model (o1, o3, GPT-5, DeepSeek)."""
-        model_lower = self.model.lower()
-        return any(x in model_lower for x in ["gpt-5", "o1", "o3", "deepseek"])
-
-    def _get_max_reasoning_tokens(self) -> int | None:
-        """Get max reasoning tokens for reasoning models."""
-        model_lower = self.model.lower()
-
-        # GPT-4 and GPT-4.1 models have different caps
-        if any(x in model_lower for x in ["gpt-4.1", "gpt-4-"]):
-            return 32000
-        elif "gpt-4o" in model_lower:
-            return 16384
-
-        return None
-
-    async def call(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None = None,
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "memory",
-        max_retries: int = 10,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 60.0,
-        skip_validation: bool = False,
-        strict_schema: bool = False,
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Make an LLM API call with retry logic.
-
-        Args:
-            messages: List of message dicts with 'role' and 'content'.
-            response_format: Optional Pydantic model for structured output.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            skip_validation: Return raw JSON without Pydantic validation.
-            strict_schema: Use strict JSON schema enforcement (OpenAI only).
-            return_usage: If True, return tuple (result, TokenUsage) instead of just result.
-
-        Returns:
-            If return_usage=False: Parsed response if response_format is provided, otherwise text content.
-            If return_usage=True: Tuple of (result, TokenUsage) with token counts.
-
-        Raises:
-            OutputTooLongError: If output exceeds token limits.
-            Exception: Re-raises API errors after retries exhausted.
-        """
-        # Handle Ollama with native API for structured output (better schema enforcement)
-        if self.provider == "ollama" and response_format is not None:
-            return await self._call_ollama_native(
-                messages=messages,
-                response_format=response_format,
-                max_completion_tokens=max_completion_tokens,
-                temperature=temperature,
-                max_retries=max_retries,
-                initial_backoff=initial_backoff,
-                max_backoff=max_backoff,
-                skip_validation=skip_validation,
-                scope=scope,
-                return_usage=return_usage,
-            )
-
-        start_time = time.time()
-
-        # Build call parameters
-        call_params: dict[str, Any] = {
-            "model": self.model,
-            "messages": messages,
-        }
-
-        # Check if model supports reasoning parameter
-        is_reasoning_model = self._supports_reasoning_model()
-
-        # Apply model-specific token limits
-        if max_completion_tokens is not None:
-            max_tokens_cap = self._get_max_reasoning_tokens()
-            if max_tokens_cap and max_completion_tokens > max_tokens_cap:
-                max_completion_tokens = max_tokens_cap
-            # For reasoning models, enforce minimum to ensure space for reasoning + output
-            if is_reasoning_model and max_completion_tokens < 16000:
-                max_completion_tokens = 16000
-            call_params["max_completion_tokens"] = max_completion_tokens
-
-        # Temperature - reasoning models don't support custom temperature
-        if temperature is not None and not is_reasoning_model:
-            call_params["temperature"] = temperature
-
-        # Set reasoning_effort for reasoning models
-        if is_reasoning_model:
-            call_params["reasoning_effort"] = self.reasoning_effort
-
-        # Provider-specific parameters
-        if self.provider == "groq":
-            call_params["seed"] = DEFAULT_LLM_SEED
-            extra_body: dict[str, Any] = {}
-            # Add service_tier if configured
-            if self.groq_service_tier:
-                extra_body["service_tier"] = self.groq_service_tier
-            # Add reasoning parameters for reasoning models
-            if is_reasoning_model:
-                extra_body["include_reasoning"] = False
-            if extra_body:
-                call_params["extra_body"] = extra_body
-
-        # Prepare response format ONCE before retry loop
-        if response_format is not None:
-            schema = None
-            if hasattr(response_format, "model_json_schema"):
-                schema = response_format.model_json_schema()
-
-            if strict_schema and schema is not None:
-                # Use OpenAI's strict JSON schema enforcement
-                call_params["response_format"] = {
-                    "type": "json_schema",
-                    "json_schema": {
-                        "name": "response",
-                        "strict": True,
-                        "schema": schema,
-                    },
-                }
-            else:
-                # Soft enforcement: add schema to prompt and use json_object mode
-                if schema is not None:
-                    schema_msg = (
-                        f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
-                    )
-
-                    if call_params["messages"] and call_params["messages"][0].get("role") == "system":
-                        first_msg = call_params["messages"][0]
-                        if isinstance(first_msg, dict) and isinstance(first_msg.get("content"), str):
-                            first_msg["content"] += schema_msg
-                    elif call_params["messages"]:
-                        first_msg = call_params["messages"][0]
-                        if isinstance(first_msg, dict) and isinstance(first_msg.get("content"), str):
-                            first_msg["content"] = schema_msg + "\n\n" + first_msg["content"]
-                if self.provider not in ("lmstudio", "ollama"):
-                    # LM Studio and Ollama don't support json_object response format reliably
-                    call_params["response_format"] = {"type": "json_object"}
-
-        last_exception = None
-
-        for attempt in range(max_retries + 1):
-            try:
-                if response_format is not None:
-                    response = await self._client.chat.completions.create(**call_params)
-
-                    content = response.choices[0].message.content
-
-                    # Strip reasoning model thinking tags
-                    # Supports: <think>, <thinking>, <reasoning>, |startthink|/|endthink|
-                    if content:
-                        original_len = len(content)
-                        content = re.sub(r"<think>.*?</think>", "", content, flags=re.DOTALL)
-                        content = re.sub(r"<thinking>.*?</thinking>", "", content, flags=re.DOTALL)
-                        content = re.sub(r"<reasoning>.*?</reasoning>", "", content, flags=re.DOTALL)
-                        content = re.sub(r"\|startthink\|.*?\|endthink\|", "", content, flags=re.DOTALL)
-                        content = content.strip()
-                        if len(content) < original_len:
-                            logger.debug(f"Stripped {original_len - len(content)} chars of reasoning tokens")
-
-                    # For local models, they may wrap JSON in markdown code blocks
-                    if self.provider in ("lmstudio", "ollama"):
-                        clean_content = content
-                        if "```json" in content:
-                            clean_content = content.split("```json")[1].split("```")[0].strip()
-                        elif "```" in content:
-                            clean_content = content.split("```")[1].split("```")[0].strip()
-                        try:
-                            json_data = json.loads(clean_content)
-                        except json.JSONDecodeError:
-                            # Fallback to parsing raw content
-                            json_data = json.loads(content)
-                    else:
-                        # Log raw LLM response for debugging JSON parse issues
-                        try:
-                            json_data = json.loads(content)
-                        except json.JSONDecodeError as json_err:
-                            # Truncate content for logging
-                            content_preview = content[:500] if content else "<empty>"
-                            if content and len(content) > 700:
-                                content_preview = f"{content[:500]}...TRUNCATED...{content[-200:]}"
-                            logger.warning(
-                                f"JSON parse error from LLM response (attempt {attempt + 1}/{max_retries + 1}): {json_err}\n"
-                                f"  Model: {self.provider}/{self.model}\n"
-                                f"  Content length: {len(content) if content else 0} chars\n"
-                                f"  Content preview: {content_preview!r}\n"
-                                f"  Finish reason: {response.choices[0].finish_reason if response.choices else 'unknown'}"
-                            )
-                            # Retry on JSON parse errors
-                            if attempt < max_retries:
-                                backoff = min(initial_backoff * (2**attempt), max_backoff)
-                                await asyncio.sleep(backoff)
-                                last_exception = json_err
-                                continue
-                            else:
-                                logger.error(f"JSON parse error after {max_retries + 1} attempts, giving up")
-                                raise
-
-                    if skip_validation:
-                        result = json_data
-                    else:
-                        result = response_format.model_validate(json_data)
-                else:
-                    response = await self._client.chat.completions.create(**call_params)
-                    result = response.choices[0].message.content
-
-                # Record token usage metrics
-                duration = time.time() - start_time
-                usage = response.usage
-                input_tokens = usage.prompt_tokens or 0 if usage else 0
-                output_tokens = usage.completion_tokens or 0 if usage else 0
-                total_tokens = usage.total_tokens or 0 if usage else 0
-
-                # Record LLM metrics
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                # Record trace span
-                from hindsight_api.tracing import _serialize_for_span, get_span_recorder
-
-                finish_reason = response.choices[0].finish_reason if response.choices else None
-                span_recorder = get_span_recorder()
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=_serialize_for_span(result),
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    duration=duration,
-                    finish_reason=finish_reason,
-                    error=None,
-                )
-
-                # Log slow calls
-                if duration > 10.0 and usage:
-                    ratio = max(1, output_tokens) / max(1, input_tokens)
-                    cached_tokens = 0
-                    if hasattr(usage, "prompt_tokens_details") and usage.prompt_tokens_details:
-                        cached_tokens = getattr(usage.prompt_tokens_details, "cached_tokens", 0) or 0
-                    cache_info = f", cached_tokens={cached_tokens}" if cached_tokens > 0 else ""
-                    logger.info(
-                        f"slow llm call: scope={scope}, model={self.provider}/{self.model}, "
-                        f"input_tokens={input_tokens}, output_tokens={output_tokens}, "
-                        f"total_tokens={total_tokens}{cache_info}, time={duration:.3f}s, ratio out/in={ratio:.2f}"
-                    )
-
-                if return_usage:
-                    token_usage = TokenUsage(
-                        input_tokens=input_tokens,
-                        output_tokens=output_tokens,
-                        total_tokens=total_tokens,
-                    )
-                    return result, token_usage
-                return result
-
-            except LengthFinishReasonError as e:
-                logger.warning(f"LLM output exceeded token limits: {str(e)}")
-                raise OutputTooLongError(
-                    "LLM output exceeded token limits. Input may need to be split into smaller chunks."
-                ) from e
-
-            except APIConnectionError as e:
-                last_exception = e
-                status_code = getattr(e, "status_code", None) or getattr(
-                    getattr(e, "response", None), "status_code", None
-                )
-                logger.warning(f"APIConnectionError (HTTP {status_code}), attempt {attempt + 1}: {str(e)[:200]}")
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    await asyncio.sleep(backoff)
-                    continue
-                else:
-                    logger.error(f"Connection error after {max_retries + 1} attempts: {str(e)}")
-                    raise
-
-            except APIStatusError as e:
-                # Fast fail only on 401 (unauthorized) and 403 (forbidden)
-                if e.status_code in (401, 403):
-                    logger.error(f"Auth error (HTTP {e.status_code}), not retrying: {str(e)}")
-                    raise
-
-                # Handle tool_use_failed error - model outputted in tool call format
-                if e.status_code == 400 and response_format is not None:
-                    try:
-                        error_body = e.body if hasattr(e, "body") else {}
-                        if isinstance(error_body, dict):
-                            error_info: dict[str, Any] = error_body.get("error") or {}
-                            if error_info.get("code") == "tool_use_failed":
-                                failed_gen = error_info.get("failed_generation", "")
-                                if failed_gen:
-                                    # Parse tool call format and convert to expected format
-                                    tool_call = json.loads(failed_gen)
-                                    tool_name = tool_call.get("name", "")
-                                    tool_args = tool_call.get("arguments", {})
-                                    converted = {"actions": [{"tool": tool_name, **tool_args}]}
-                                    if skip_validation:
-                                        result = converted
-                                    else:
-                                        result = response_format.model_validate(converted)
-
-                                    # Record metrics
-                                    duration = time.time() - start_time
-                                    metrics = get_metrics_collector()
-                                    metrics.record_llm_call(
-                                        provider=self.provider,
-                                        model=self.model,
-                                        scope=scope,
-                                        duration=duration,
-                                        input_tokens=0,
-                                        output_tokens=0,
-                                        success=True,
-                                    )
-                                    if return_usage:
-                                        return result, TokenUsage(input_tokens=0, output_tokens=0, total_tokens=0)
-                                    return result
-                    except (json.JSONDecodeError, KeyError, TypeError):
-                        pass  # Failed to parse tool_use_failed, continue with normal retry
-
-                last_exception = e
-                if attempt < max_retries:
-                    backoff = min(initial_backoff * (2**attempt), max_backoff)
-                    jitter = backoff * 0.2 * (2 * (time.time() % 1) - 1)
-                    sleep_time = backoff + jitter
-                    await asyncio.sleep(sleep_time)
-                else:
-                    logger.error(f"API error after {max_retries + 1} attempts: {str(e)}")
-                    raise
-
-            except Exception:
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("LLM call failed after all retries with no exception captured")
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None = None,
-        temperature: float | None = None,
-        scope: str = "tools",
-        max_retries: int = 5,
-        initial_backoff: float = 1.0,
-        max_backoff: float = 30.0,
-        tool_choice: str | dict[str, Any] = "auto",
-    ) -> LLMToolCallResult:
-        """
-        Make an LLM API call with tool/function calling support.
-
-        Args:
-            messages: List of message dicts. Can include tool results with role='tool'.
-            tools: List of tool definitions in OpenAI format.
-            max_completion_tokens: Maximum tokens in response.
-            temperature: Sampling temperature (0.0-2.0).
-            scope: Scope identifier for tracking.
-            max_retries: Maximum retry attempts.
-            initial_backoff: Initial backoff time in seconds.
-            max_backoff: Maximum backoff time in seconds.
-            tool_choice: How to choose tools - "auto", "none", "required", or specific function.
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        start_time = time.time()
-
-        # Build call parameters
-        call_params: dict[str, Any] = {
-            "model": self.model,
-            "messages": messages,
-            "tools": tools,
-            "tool_choice": tool_choice,
-        }
-
-        if max_completion_tokens is not None:
-            call_params["max_completion_tokens"] = max_completion_tokens
-        if temperature is not None:
-            call_params["temperature"] = temperature
-
-        # Provider-specific parameters
-        if self.provider == "groq":
-            call_params["seed"] = DEFAULT_LLM_SEED
-
-        last_exception = None
-
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._client.chat.completions.create(**call_params)
-
-                message = response.choices[0].message
-                finish_reason = response.choices[0].finish_reason
-
-                # Extract tool calls if present
-                tool_calls: list[LLMToolCall] = []
-                if message.tool_calls:
-                    for tc in message.tool_calls:
-                        try:
-                            args = json.loads(tc.function.arguments) if tc.function.arguments else {}
-                        except json.JSONDecodeError:
-                            args = {"_raw": tc.function.arguments}
-                        tool_calls.append(LLMToolCall(id=tc.id, name=tc.function.name, arguments=args))
-
-                content = message.content
-
-                # Record metrics
-                duration = time.time() - start_time
-                usage = response.usage
-                input_tokens = usage.prompt_tokens or 0 if usage else 0
-                output_tokens = usage.completion_tokens or 0 if usage else 0
-
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=duration,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                # Record OpenTelemetry span
-                from hindsight_api.tracing import get_span_recorder
-
-                span_recorder = get_span_recorder()
-                # Convert LLMToolCall objects to dicts for span recording
-                tool_calls_dict = (
-                    [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls]
-                    if tool_calls
-                    else None
-                )
-                span_recorder.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    messages=messages,
-                    response_content=content,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    duration=duration,
-                    finish_reason=finish_reason,
-                    error=None,
-                    tool_calls=tool_calls_dict,
-                )
-
-                return LLMToolCallResult(
-                    content=content,
-                    tool_calls=tool_calls,
-                    finish_reason=finish_reason,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                )
-
-            except APIConnectionError as e:
-                last_exception = e
-                if attempt < max_retries:
-                    await asyncio.sleep(min(initial_backoff * (2**attempt), max_backoff))
-                    continue
-                raise
-
-            except APIStatusError as e:
-                if e.status_code in (401, 403):
-                    raise
-                last_exception = e
-                if attempt < max_retries:
-                    await asyncio.sleep(min(initial_backoff * (2**attempt), max_backoff))
-                    continue
-                raise
-
-            except Exception:
-                raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Tool call failed after all retries")
-
-    async def _call_ollama_native(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any,
-        max_completion_tokens: int | None,
-        temperature: float | None,
-        max_retries: int,
-        initial_backoff: float,
-        max_backoff: float,
-        skip_validation: bool,
-        scope: str = "memory",
-        return_usage: bool = False,
-    ) -> Any:
-        """
-        Call Ollama using native API with JSON schema enforcement.
-
-        Ollama's native API supports passing a full JSON schema in the 'format' parameter,
-        which provides better structured output control than the OpenAI-compatible API.
-        """
-        start_time = time.time()
-
-        # Get the JSON schema from the Pydantic model
-        schema = response_format.model_json_schema() if hasattr(response_format, "model_json_schema") else None
-
-        # Build the base URL for Ollama's native API
-        # Default OpenAI-compatible URL is http://localhost:11434/v1
-        # Native API is at http://localhost:11434/api/chat
-        base_url = self.base_url or "http://localhost:11434/v1"
-        if base_url.endswith("/v1"):
-            native_url = base_url[:-3] + "/api/chat"
-        else:
-            native_url = base_url.rstrip("/") + "/api/chat"
-
-        # Build request payload
-        payload: dict[str, Any] = {
-            "model": self.model,
-            "messages": messages,
-            "stream": False,
-        }
-
-        # Add schema as format parameter for structured output
-        if schema:
-            payload["format"] = schema
-
-        # Add optional parameters with optimized defaults for Ollama
-        options: dict[str, Any] = {
-            "num_ctx": 16384,  # 16k context window for larger prompts
-            "num_batch": 512,  # Optimal batch size for prompt processing
-        }
-        if max_completion_tokens:
-            options["num_predict"] = max_completion_tokens
-        if temperature is not None:
-            options["temperature"] = temperature
-        payload["options"] = options
-
-        last_exception = None
-
-        async with httpx.AsyncClient(timeout=300.0) as client:
-            for attempt in range(max_retries + 1):
-                try:
-                    response = await client.post(native_url, json=payload)
-                    response.raise_for_status()
-
-                    result = response.json()
-                    content = result.get("message", {}).get("content", "")
-
-                    # Parse JSON response
-                    try:
-                        json_data = json.loads(content)
-                    except json.JSONDecodeError as json_err:
-                        content_preview = content[:500] if content else "<empty>"
-                        if content and len(content) > 700:
-                            content_preview = f"{content[:500]}...TRUNCATED...{content[-200:]}"
-                        logger.warning(
-                            f"Ollama JSON parse error (attempt {attempt + 1}/{max_retries + 1}): {json_err}\n"
-                            f"  Model: ollama/{self.model}\n"
-                            f"  Content length: {len(content) if content else 0} chars\n"
-                            f"  Content preview: {content_preview!r}"
-                        )
-                        if attempt < max_retries:
-                            backoff = min(initial_backoff * (2**attempt), max_backoff)
-                            await asyncio.sleep(backoff)
-                            last_exception = json_err
-                            continue
-                        else:
-                            raise
-
-                    # Extract token usage from Ollama response
-                    duration = time.time() - start_time
-                    input_tokens = result.get("prompt_eval_count", 0) or 0
-                    output_tokens = result.get("eval_count", 0) or 0
-                    total_tokens = input_tokens + output_tokens
-
-                    # Record LLM metrics
-                    metrics = get_metrics_collector()
-                    metrics.record_llm_call(
-                        provider=self.provider,
-                        model=self.model,
-                        scope=scope,
-                        duration=duration,
-                        input_tokens=input_tokens,
-                        output_tokens=output_tokens,
-                        success=True,
-                    )
-
-                    # Validate against Pydantic model or return raw JSON
-                    if skip_validation:
-                        validated_result = json_data
-                    else:
-                        validated_result = response_format.model_validate(json_data)
-
-                    if return_usage:
-                        token_usage = TokenUsage(
-                            input_tokens=input_tokens,
-                            output_tokens=output_tokens,
-                            total_tokens=total_tokens,
-                        )
-                        return validated_result, token_usage
-                    return validated_result
-
-                except httpx.HTTPStatusError as e:
-                    last_exception = e
-                    if attempt < max_retries:
-                        logger.warning(
-                            f"Ollama HTTP error (attempt {attempt + 1}/{max_retries + 1}): {e.response.status_code}"
-                        )
-                        backoff = min(initial_backoff * (2**attempt), max_backoff)
-                        await asyncio.sleep(backoff)
-                        continue
-                    else:
-                        logger.error(f"Ollama HTTP error after {max_retries + 1} attempts: {e}")
-                        raise
-
-                except httpx.RequestError as e:
-                    last_exception = e
-                    if attempt < max_retries:
-                        logger.warning(f"Ollama connection error (attempt {attempt + 1}/{max_retries + 1}): {e}")
-                        backoff = min(initial_backoff * (2**attempt), max_backoff)
-                        await asyncio.sleep(backoff)
-                        continue
-                    else:
-                        logger.error(f"Ollama connection error after {max_retries + 1} attempts: {e}")
-                        raise
-
-                except Exception as e:
-                    logger.error(f"Unexpected error during Ollama call: {type(e).__name__}: {e}")
-                    raise
-
-        if last_exception:
-            raise last_exception
-        raise RuntimeError("Ollama call failed after all retries")
-
-    async def cleanup(self) -> None:
-        """Clean up resources (close OpenAI client connections)."""
-        if hasattr(self, "_client") and self._client:
-            await self._client.close()
@@ -4,15 +4,17 @@ Reflect agent module for agentic reflection with tools.
 The reflect agent uses an iterative loop with tools to:
 1. Lookup mental models (existing knowledge)
 2. Recall facts (semantic + temporal search)
-3. Expand memories (get chunk/document context)
+3. Learn new insights (create/update mental models)
+4. Expand memories (get chunk/document context)
 """

 from .agent import ReflectAgentResult, run_reflect_agent
-from .models import ReflectAction, ReflectActionBatch
+from .models import MentalModelInput, ReflectAction, ReflectActionBatch

 __all__ = [
    "run_reflect_agent",
    "ReflectAgentResult",
    "ReflectAction",
    "ReflectActionBatch",
+    "MentalModelInput",
 ]
@@ -2,8 +2,8 @@
 Reflect agent - agentic loop for reflection with native tool calling.

 Uses hierarchical retrieval:
-1. search_mental_models - User-curated summaries (highest quality)
-2. search_observations - Consolidated knowledge with freshness
+1. search_reflections - User-curated summaries (highest quality)
+2. search_mental_models - Consolidated knowledge with freshness
 3. recall - Raw facts as ground truth
 """

@@ -20,12 +20,7 @@ from .tools_schema import get_reflect_tools


 def _build_directives_applied(directives: list[dict[str, Any]] | None) -> list[DirectiveInfo]:
-    """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
-    """
+    """Build list of DirectiveInfo from directive mental models."""
    if not directives:
        return []

@@ -33,11 +28,17 @@ def _build_directives_applied(directives: list[dict[str, Any]] | None) -> list[D
    for directive in directives:
        directive_id = directive.get("id", "")
        directive_name = directive.get("name", "")
+        observations = directive.get("observations", [])

-        # Get content from 'content' field or fallback to 'description'
-        content = directive.get("content", "") or directive.get("description", "")
+        rules = []
+        for obs in observations:
+            # Support both Pydantic Observation objects and dicts
+            if hasattr(obs, "content"):
+                rules.append(obs.content)
+            elif isinstance(obs, dict) and obs.get("content"):
+                rules.append(obs["content"])

-        result.append(DirectiveInfo(id=directive_id, name=directive_name, content=content))
+        result.append(DirectiveInfo(id=directive_id, name=directive_name, rules=rules))

    return result

@@ -58,7 +59,6 @@ def _normalize_tool_name(name: str) -> str:
    - 'functions.done' (OpenAI-style prefix)
    - 'call=functions.done' (some models)
    - 'call=done' (some models)
-    - 'done<|channel|>commentary' (malformed special tokens appended)

    Returns the normalized tool name (e.g., 'done', 'recall', etc.)
    """
@@ -70,11 +70,6 @@ def _normalize_tool_name(name: str) -> str:
    if name.startswith("functions."):
        name = name[len("functions.") :]

-    # Handle malformed special tokens appended to tool name
-    # e.g., 'done<|channel|>commentary' -> 'done'
-    if "<|" in name:
-        name = name.split("<|")[0]
-
    return name


@@ -86,18 +81,6 @@ def _is_done_tool(name: str) -> bool:
 # Pattern to match done() call as text - handles done({...}) with nested JSON
 _DONE_CALL_PATTERN = re.compile(r"done\s*\(\s*\{.*$", re.DOTALL)

-# Patterns for leaked structured output in the answer field
-_LEAKED_JSON_SUFFIX = re.compile(
-    r'\s*```(?:json)?\s*\{[^}]*(?:"(?:observation_ids|memory_ids|mental_model_ids)"|\})\s*```\s*$',
-    re.DOTALL | re.IGNORECASE,
-)
-_LEAKED_JSON_OBJECT = re.compile(
-    r'\s*\{[^{]*"(?:observation_ids|memory_ids|mental_model_ids|answer)"[^}]*\}\s*$', re.DOTALL
-)
-_TRAILING_IDS_PATTERN = re.compile(
-    r"\s*(?:observation_ids|memory_ids|mental_model_ids)\s*[=:]\s*\[.*?\]\s*$", re.DOTALL | re.IGNORECASE
-)
-

 def _clean_answer_text(text: str) -> str:
    """Clean up answer text by removing any done() tool call syntax.
@@ -110,33 +93,6 @@ def _clean_answer_text(text: str) -> str:
    return cleaned if cleaned else text


-def _clean_done_answer(text: str) -> str:
-    """Clean up the answer field from a done() tool call.
-
-    Some LLMs leak structured output patterns into the answer text, such as:
-    - JSON code blocks with observation_ids/memory_ids at the end
-    - Raw JSON objects with these fields
-    - Plain text like "observation_ids: [...]"
-
-    This cleans those patterns while preserving the actual answer content.
-    """
-    if not text:
-        return text
-
-    cleaned = text
-
-    # Remove leaked JSON in code blocks at the end
-    cleaned = _LEAKED_JSON_SUFFIX.sub("", cleaned).strip()
-
-    # Remove leaked raw JSON objects at the end
-    cleaned = _LEAKED_JSON_OBJECT.sub("", cleaned).strip()
-
-    # Remove trailing ID patterns
-    cleaned = _TRAILING_IDS_PATTERN.sub("", cleaned).strip()
-
-    return cleaned if cleaned else text
-
-
 async def _generate_structured_output(
    answer: str,
    response_schema: dict,
@@ -186,55 +142,35 @@ async def _generate_structured_output(
            fields[field_name] = (field_type, default)

        if not fields:
-            logger.warning(f"[REFLECT {reflect_id}] No fields found in response_schema, skipping structured output")
-            return None, 0, 0
+            return None

        DynamicModel = create_model("StructuredResponse", **fields)

        # Include the full schema in the prompt for better LLM guidance
        schema_str = json.dumps(response_schema, indent=2)

-        # Build field descriptions for the prompt
-        field_descriptions = []
-        for field_name, field_schema in schema_props.items():
-            field_type = field_schema.get("type", "string")
-            field_desc = field_schema.get("description", "")
-            is_required = field_name in required_fields
-            req_marker = " (REQUIRED)" if is_required else " (optional)"
-            field_descriptions.append(f"- {field_name} ({field_type}){req_marker}: {field_desc}")
-        fields_text = "\n".join(field_descriptions)
-
        # Call LLM with the answer to extract structured data
-        structured_prompt = f"""Your task is to extract specific information from the answer below and format it as JSON.
+        structured_prompt = f"""Based on this answer, extract the information into the requested structured format.

-ANSWER TO EXTRACT FROM:
-\"\"\"
-{answer}
-\"\"\"
+Answer: {answer}

-REQUIRED OUTPUT FORMAT - Extract the following fields from the answer above:
-{fields_text}
-
-JSON Schema:
+JSON Schema to follow:
 ```json
 {schema_str}
 ```

-INSTRUCTIONS:
-1. Read the answer carefully and identify the information that matches each field
-2. Extract the ACTUAL content from the answer - do NOT leave fields empty if information is present
-3. For string fields: use the exact text or a clear summary from the answer
-4. For array fields: return a JSON array (e.g., ["item1", "item2"]), NOT a string
-5. For required fields: you MUST provide a value extracted from the answer
-6. Return ONLY the JSON object, no explanation
+Return ONLY a valid JSON object that matches this exact schema. Pay special attention to field types:
+- "type": "array" means the value must be a JSON array/list, NOT a string
+- "type": "string" means the value must be a string
+- "type": "object" means the value must be a JSON object

-OUTPUT:"""
+Do not include any explanation, only the JSON object."""

        structured_result, usage = await llm_config.call(
            messages=[
                {
                    "role": "system",
-                    "content": "You are a precise data extraction assistant. Extract information from text and return it as valid JSON matching the provided schema. Always extract actual content - never return empty strings for required fields if information is available.",
+                    "content": "Extract structured data from the given answer. Return only valid JSON matching the provided schema exactly.",
                },
                {"role": "user", "content": structured_prompt},
            ],
@@ -253,12 +189,6 @@ OUTPUT:"""
            # Try to parse as JSON
            structured_output = json.loads(str(structured_result))

-        # Validate that required fields have non-empty values
-        for field_name in required_fields:
-            value = structured_output.get(field_name)
-            if value is None or value == "" or value == []:
-                logger.warning(f"[REFLECT {reflect_id}] Required field '{field_name}' is empty in structured output")
-
        logger.info(f"[REFLECT {reflect_id}] Generated structured output with {len(structured_output)} fields")
        return structured_output, usage.input_tokens, usage.output_tokens

@@ -272,8 +202,8 @@ async def run_reflect_agent(
    bank_id: str,
    query: str,
    bank_profile: dict[str, Any],
+    search_reflections_fn: Callable[[str, int], Awaitable[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], Awaitable[dict[str, Any]]],
    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
    context: str | None = None,
@@ -281,15 +211,13 @@ async def run_reflect_agent(
    max_tokens: int | None = None,
    response_schema: dict | None = None,
    directives: list[dict[str, Any]] | None = None,
-    has_mental_models: bool = False,
-    budget: str | None = None,
 ) -> ReflectAgentResult:
    """
    Execute the reflect agent loop using native tool calling.

    The agent uses hierarchical retrieval:
-    1. search_mental_models - User-curated summaries (try first)
-    2. search_observations - Consolidated knowledge with freshness
+    1. search_reflections - User-curated summaries (try first)
+    2. search_mental_models - Consolidated knowledge with freshness
    3. recall - Raw facts as ground truth

    Args:
@@ -297,8 +225,8 @@ async def run_reflect_agent(
        bank_id: Bank identifier
        query: Question to answer
        bank_profile: Bank profile with name and mission
+        search_reflections_fn: Tool callback for searching reflections (query, max_results) -> result
        search_mental_models_fn: Tool callback for searching mental models (query, max_results) -> result
-        search_observations_fn: Tool callback for searching observations (query, max_results) -> result
        recall_fn: Tool callback for recall (query, max_tokens) -> result
        expand_fn: Tool callback for expand (memory_ids, depth) -> result
        context: Optional additional context
@@ -323,9 +251,7 @@ async def run_reflect_agent(
    tools = get_reflect_tools(directive_rules=directive_rules)

    # Build initial messages (directives are injected into system prompt at START and END)
-    system_prompt = build_system_prompt_for_tools(
-        bank_profile, context, directives=directives, has_mental_models=has_mental_models, budget=budget
-    )
+    system_prompt = build_system_prompt_for_tools(bank_profile, context, directives=directives)
    messages: list[dict[str, Any]] = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": query},
@@ -344,8 +270,8 @@ async def run_reflect_agent(

    # Track available IDs for validation (prevents hallucinated citations)
    available_memory_ids: set[str] = set()
+    available_reflection_ids: set[str] = set()
    available_mental_model_ids: set[str] = set()
-    available_observation_ids: set[str] = set()

    def _get_llm_trace() -> list[LLMCall]:
        return [
@@ -402,7 +328,7 @@ async def run_reflect_agent(
                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                    {"role": "user", "content": prompt},
                ],
-                scope="reflect",
+                scope="reflect_agent_final",
                max_completion_tokens=max_tokens,
                return_usage=True,
            )
@@ -447,7 +373,7 @@ async def run_reflect_agent(
            result = await llm_config.call_with_tools(
                messages=messages,
                tools=tools,
-                scope="reflect_tool_call",
+                scope="reflect_agent",
                tool_choice="required" if iteration == 0 else "auto",  # Force tool use on first iteration
            )
            llm_duration = int((time.time() - llm_start) * 1000)
@@ -468,7 +394,7 @@ async def run_reflect_agent(
            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)
+                bool(available_memory_ids) or bool(available_reflection_ids) or bool(available_mental_model_ids)
            )
            if not has_gathered_evidence and iteration < max_iterations - 1:
                continue
@@ -479,7 +405,7 @@ async def run_reflect_agent(
                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                    {"role": "user", "content": prompt},
                ],
-                scope="reflect",
+                scope="reflect_agent_final",
                max_completion_tokens=max_tokens,
                return_usage=True,
            )
@@ -550,7 +476,7 @@ async def run_reflect_agent(
                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                    {"role": "user", "content": prompt},
                ],
-                scope="reflect",
+                scope="reflect_agent_final",
                max_completion_tokens=max_tokens,
                return_usage=True,
            )
@@ -593,7 +519,7 @@ async def run_reflect_agent(
        if done_call:
            # Guardrail: Require evidence before done
            has_gathered_evidence = (
-                bool(available_memory_ids) or bool(available_mental_model_ids) or bool(available_observation_ids)
+                bool(available_memory_ids) or bool(available_reflection_ids) or bool(available_mental_model_ids)
            )
            if not has_gathered_evidence and iteration < max_iterations - 1:
                # Add assistant message and fake tool result asking for evidence
@@ -610,37 +536,30 @@ async def run_reflect_agent(
                        "name": done_call.name,  # Required by Gemini
                        "content": json.dumps(
                            {
-                                "error": "You must search for information first. Use search_mental_models(), search_observations(), or recall() before providing your final answer."
+                                "error": "You must search for information first. Use search_reflections(), search_mental_models(), or recall() before providing your final answer."
                            }
                        ),
                    }
                )
                continue

-            # Process done tool - wrap with tool call span
-            from hindsight_api.tracing import get_tracer
-
-            tracer = get_tracer()
-            span_name = "hindsight.reflect_tool_call"
-            with tracer.start_as_current_span(span_name) as span:
-                span.set_attribute("hindsight.scope", "reflect_tool_call")
-                span.set_attribute("hindsight.operation", "reflect_tool_call")
-                return await _process_done_tool(
-                    done_call,
-                    available_memory_ids,
-                    available_mental_model_ids,
-                    available_observation_ids,
-                    iteration + 1,
-                    total_tools_called,
-                    tool_trace,
-                    _get_llm_trace(),
-                    _get_usage(),
-                    _log_completion,
-                    reflect_id,
-                    directives_applied=directives_applied,
-                    llm_config=llm_config,
-                    response_schema=response_schema,
-                )
+            # Process done tool
+            return await _process_done_tool(
+                done_call,
+                available_memory_ids,
+                available_reflection_ids,
+                available_mental_model_ids,
+                iteration + 1,
+                total_tools_called,
+                tool_trace,
+                _get_llm_trace(),
+                _get_usage(),
+                _log_completion,
+                reflect_id,
+                directives_applied=directives_applied,
+                llm_config=llm_config,
+                response_schema=response_schema,
+            )

        # Execute other tools in parallel (exclude done tool in all its format variants)
        other_tools = [tc for tc in result.tool_calls if not _is_done_tool(tc.name)]
@@ -657,8 +576,8 @@ async def run_reflect_agent(
            tool_tasks = [
                _execute_tool_with_timing(
                    tc,
+                    search_reflections_fn,
                    search_mental_models_fn,
-                    search_observations_fn,
                    recall_fn,
                    expand_fn,
                )
@@ -687,6 +606,15 @@ async def run_reflect_agent(
                    )

                # Track available IDs from tool results (only for successful responses)
+                if (
+                    normalized_tool_name == "search_reflections"
+                    and isinstance(output, dict)
+                    and "reflections" in output
+                ):
+                    for reflection in output["reflections"]:
+                        if "id" in reflection:
+                            available_reflection_ids.add(reflection["id"])
+
                if (
                    normalized_tool_name == "search_mental_models"
                    and isinstance(output, dict)
@@ -696,15 +624,6 @@ async def run_reflect_agent(
                        if "id" in mm:
                            available_mental_model_ids.add(mm["id"])

-                if (
-                    normalized_tool_name == "search_observations"
-                    and isinstance(output, dict)
-                    and "observations" in output
-                ):
-                    for obs in output["observations"]:
-                        if "id" in obs:
-                            available_observation_ids.add(obs["id"])
-
                if normalized_tool_name == "recall" and isinstance(output, dict) and "memories" in output:
                    for memory in output["memories"]:
                        if "id" in memory:
@@ -724,17 +643,9 @@ async def run_reflect_agent(
                input_dict = {"tool": tc.name, **tc.arguments}
                input_summary = _summarize_input(tc.name, tc.arguments)

-                # Extract reason from tool arguments (if provided)
-                tool_reason = tc.arguments.get("reason")
-
                tool_trace.append(
                    ToolCall(
-                        tool=tc.name,
-                        reason=tool_reason,
-                        input=input_dict,
-                        output=output,
-                        duration_ms=duration_ms,
-                        iteration=iteration + 1,
+                        tool=tc.name, input=input_dict, output=output, duration_ms=duration_ms, iteration=iteration + 1
                    )
                )

@@ -784,8 +695,8 @@ def _tool_call_to_dict(tc: "LLMToolCall") -> dict[str, Any]:
 async def _process_done_tool(
    done_call: "LLMToolCall",
    available_memory_ids: set[str],
+    available_reflection_ids: set[str],
    available_mental_model_ids: set[str],
-    available_observation_ids: set[str],
    iterations: int,
    total_tools_called: int,
    tool_trace: list[ToolCall],
@@ -800,16 +711,14 @@ async def _process_done_tool(
    """Process the done tool call and return the result."""
    args = done_call.arguments

-    # Extract and clean the answer - some LLMs leak structured output into the answer text
-    raw_answer = args.get("answer", "").strip()
-    answer = _clean_done_answer(raw_answer) if raw_answer else ""
+    answer = args.get("answer", "").strip()
    if not answer:
        answer = "No answer provided."

    # Validate IDs (only include IDs that were actually retrieved)
    used_memory_ids = [mid for mid in args.get("memory_ids", []) if mid in available_memory_ids]
+    used_reflection_ids = [rid for rid in args.get("reflection_ids", []) if rid in available_reflection_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
@@ -835,88 +744,38 @@ async def _process_done_tool(
        llm_trace=llm_trace,
        usage=final_usage,
        used_memory_ids=used_memory_ids,
+        used_reflection_ids=used_reflection_ids,
        used_mental_model_ids=used_mental_model_ids,
-        used_observation_ids=used_observation_ids,
        directives_applied=directives_applied,
    )


 async def _execute_tool_with_timing(
    tc: "LLMToolCall",
+    search_reflections_fn: Callable[[str, int], Awaitable[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], 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."""
-    from hindsight_api.tracing import get_tracer
-
-    start_time = time.time()
-
-    # Create span for tool execution
-    tracer = get_tracer()
-    # Normalize tool name for span
-    normalized_name = _normalize_tool_name(tc.name)
-    span_name = f"hindsight.reflect_tool_exec.{normalized_name}"
-
-    # Calculate timestamps
-    start_time_ns = time.time_ns()
-
-    with tracer.start_as_current_span(
-        span_name,
-        start_time=start_time_ns,
-        end_on_exit=False,
-    ) as span:
-        # Set attributes
-        span.set_attribute("hindsight.tool.name", normalized_name)
-        span.set_attribute("hindsight.tool.id", tc.id)
-        span.set_attribute("hindsight.tool.arguments", json.dumps(tc.arguments))
-
-        try:
-            result = await _execute_tool(
-                tc.name,
-                tc.arguments,
-                search_mental_models_fn,
-                search_observations_fn,
-                recall_fn,
-                expand_fn,
-            )
-
-            # Set success attributes
-            if isinstance(result, dict) and "error" in result:
-                from opentelemetry.trace import Status, StatusCode
-
-                span.set_status(Status(StatusCode.ERROR, result["error"]))
-            else:
-                from opentelemetry.trace import Status, StatusCode
-
-                span.set_status(Status(StatusCode.OK))
-
-            duration_ms = int((time.time() - start_time) * 1000)
-            span.set_attribute("hindsight.tool.duration_ms", duration_ms)
-
-            # End span with correct timestamp
-            end_time_ns = time.time_ns()
-            span.end(end_time=end_time_ns)
-
-            return result, duration_ms
-        except Exception as e:
-            from opentelemetry.trace import Status, StatusCode
-
-            span.set_status(Status(StatusCode.ERROR, str(e)))
-            span.record_exception(e)
-            duration_ms = int((time.time() - start_time) * 1000)
-            span.set_attribute("hindsight.tool.duration_ms", duration_ms)
-            end_time_ns = time.time_ns()
-            span.end(end_time=end_time_ns)
-            raise
+    start = time.time()
+    result = await _execute_tool(
+        tc.name,
+        tc.arguments,
+        search_reflections_fn,
+        search_mental_models_fn,
+        recall_fn,
+        expand_fn,
+    )
+    duration_ms = int((time.time() - start) * 1000)
+    return result, duration_ms


 async def _execute_tool(
    tool_name: str,
    args: dict[str, Any],
+    search_reflections_fn: Callable[[str, int], Awaitable[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], Awaitable[dict[str, Any]]],
    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
 ) -> dict[str, Any]:
@@ -924,25 +783,25 @@ async def _execute_tool(
    # Normalize tool name for various LLM output formats
    tool_name = _normalize_tool_name(tool_name)

-    if tool_name == "search_mental_models":
+    if tool_name == "search_reflections":
+        query = args.get("query")
+        if not query:
+            return {"error": "search_reflections requires a query parameter"}
+        max_results = args.get("max_results") or 5
+        return await search_reflections_fn(query, max_results)
+
+    elif tool_name == "search_mental_models":
        query = args.get("query")
        if not query:
            return {"error": "search_mental_models requires a query parameter"}
-        max_results = int(args.get("max_results") or 5)
-        return await search_mental_models_fn(query, max_results)
-
-    elif tool_name == "search_observations":
-        query = args.get("query")
-        if not query:
-            return {"error": "search_observations requires a query parameter"}
-        max_tokens = max(int(args.get("max_tokens") or 5000), 1000)  # Default 5000, min 1000
-        return await search_observations_fn(query, max_tokens)
+        max_tokens = max(args.get("max_tokens") or 5000, 1000)  # Default 5000, min 1000
+        return await search_mental_models_fn(query, max_tokens)

    elif tool_name == "recall":
        query = args.get("query")
        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_tokens = max(args.get("max_tokens") or 2048, 1000)  # Default 2048, min 1000
        return await recall_fn(query, max_tokens)

    elif tool_name == "expand":
@@ -958,21 +817,21 @@ async def _execute_tool(

 def _summarize_input(tool_name: str, args: dict[str, Any]) -> str:
    """Create a summary of tool input for logging, showing all params."""
-    if tool_name == "search_mental_models":
+    if tool_name == "search_reflections":
        query = args.get("query", "")
        query_preview = f"'{query[:30]}...'" if len(query) > 30 else f"'{query}'"
-        max_results = int(args.get("max_results") or 5)
+        max_results = args.get("max_results") or 5
        return f"(query={query_preview}, max_results={max_results})"
-    elif tool_name == "search_observations":
+    elif tool_name == "search_mental_models":
        query = args.get("query", "")
        query_preview = f"'{query[:30]}...'" if len(query) > 30 else f"'{query}'"
-        max_tokens = max(int(args.get("max_tokens") or 5000), 1000)
+        max_tokens = max(args.get("max_tokens") or 5000, 1000)
        return f"(query={query_preview}, max_tokens={max_tokens})"
    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_tokens = max(args.get("max_tokens") or 2048, 1000)
        return f"(query={query_preview}, max_tokens={max_tokens})"
    elif tool_name == "expand":
        memory_ids = args.get("memory_ids", [])
@@ -982,9 +841,9 @@ def _summarize_input(tool_name: str, args: dict[str, Any]) -> str:
        answer = args.get("answer", "")
        answer_preview = f"'{answer[:30]}...'" if len(answer) > 30 else f"'{answer}'"
        memory_ids = args.get("memory_ids", [])
+        reflection_ids = args.get("reflection_ids", [])
        mental_model_ids = args.get("mental_model_ids", [])
-        observation_ids = args.get("observation_ids", [])
        return (
-            f"(answer={answer_preview}, mem={len(memory_ids)}, mm={len(mental_model_ids)}, obs={len(observation_ids)})"
+            f"(answer={answer_preview}, mem={len(memory_ids)}, ref={len(reflection_ids)}, mm={len(mental_model_ids)})"
        )
    return str(args)
@@ -7,31 +7,54 @@ from typing import Any, Literal
 from pydantic import BaseModel, Field


-class ObservationSection(BaseModel):
-    """A section within an observation with its supporting memories."""
+class MentalModelObservation(BaseModel):
+    """An observation within a mental model with its supporting memories."""

-    title: str = Field(description="Section header (can be empty for intro)")
-    text: str = Field(description="Section content - no headers, use lists/tables/bold")
+    title: str = Field(description="Observation header (can be empty for intro)")
+    text: str = Field(description="Observation content - no headers, use lists/tables/bold")
+    memory_ids: list[str] = Field(default_factory=list, description="Memory IDs supporting this observation")
+
+
+class MentalModelInput(BaseModel):
+    """Input for the learn tool to create a mental model placeholder.
+
+    The agent only specifies name and description - the actual content/observations
+    are generated during refresh, similar to pinned models.
+    """
+
+    name: str = Field(description="Human-readable name for the mental model")
+    description: str = Field(description="What to track - used as prompt for content generation during refresh")
+    entity_id: str | None = Field(default=None, description="Optional link to existing entity ID")
+
+
+class AnswerSection(BaseModel):
+    """A section of the answer with its supporting evidence (DEPRECATED)."""
+
+    title: str = Field(description="Section header/title")
+    text: str = Field(description="Section content")
    memory_ids: list[str] = Field(default_factory=list, description="Memory IDs supporting this section")
+    model_ids: list[str] = Field(default_factory=list, description="Mental model IDs supporting this section")


 class ReflectAction(BaseModel):
    """Single action the reflect agent can take."""

-    tool: Literal["list_observations", "get_observation", "recall", "expand", "done"] = Field(
-        description="Tool to invoke: list_observations, get_observation, recall, expand, or done"
+    tool: Literal["list_mental_models", "get_mental_model", "recall", "learn", "expand", "done"] = Field(
+        description="Tool to invoke: list_mental_models, get_mental_model, recall, learn, expand, or done"
    )
    # Tool-specific parameters
-    observation_id: str | None = Field(default=None, description="Observation ID for get_observation")
+    model_id: str | None = Field(default=None, description="Mental model ID for get_mental_model")
    query: str | None = Field(default=None, description="Search query for recall")
    max_tokens: int | None = Field(default=None, description="Max tokens for recall results (default 2048)")
+    mental_model: MentalModelInput | None = Field(default=None, description="Mental model to create/update for learn")
    memory_ids: list[str] | None = Field(default=None, description="Memory unit IDs for expand (batched)")
    depth: Literal["chunk", "document"] | None = Field(default=None, description="Expansion depth for expand")
-    observation_sections: list[ObservationSection] | None = Field(
-        default=None, description="Observation sections for done action (when output_mode=observations)"
+    sections: list[AnswerSection] | None = Field(default=None, description="DEPRECATED: Use answer field instead")
+    observations: list[MentalModelObservation] | None = Field(
+        default=None, description="Observations for done action (when output_mode=observations)"
    )
    # Plain text answer fields (for output_mode=answer)
-    answer: str | None = Field(default=None, description="Well-formatted markdown answer for done action")
+    answer: str | None = Field(default=None, description="Plain text answer for done action (no markdown)")
    answer_memory_ids: list[str] | None = Field(
        default=None, description="Memory IDs supporting the answer", alias="memory_ids"
    )
@@ -50,8 +73,7 @@ class ReflectActionBatch(BaseModel):
 class ToolCall(BaseModel):
    """A single tool call made during reflect."""

-    tool: str = Field(description="Tool name: lookup, recall, expand")
-    reason: str | None = Field(default=None, description="Agent's reasoning for making this tool call")
+    tool: str = Field(description="Tool name: lookup, recall, learn, expand")
    input: dict = Field(description="Tool input parameters")
    output: dict = Field(description="Tool output/result")
    duration_ms: int = Field(description="Execution time in milliseconds")
@@ -72,7 +94,7 @@ class DirectiveInfo(BaseModel):

    id: str = Field(description="Directive mental model ID")
    name: str = Field(description="Directive name")
-    content: str = Field(description="Directive content")
+    rules: list[str] = Field(default_factory=list, description="Directive rules/observations that were applied")


 class TokenUsageSummary(BaseModel):
@@ -98,12 +120,12 @@ class ReflectAgentResult(BaseModel):
        default_factory=TokenUsageSummary, description="Total token usage across all LLM calls"
    )
    used_memory_ids: list[str] = Field(default_factory=list, description="Validated memory IDs actually used in answer")
+    used_reflection_ids: list[str] = Field(
+        default_factory=list, description="Validated reflection IDs actually used in answer"
+    )
    used_mental_model_ids: list[str] = Field(
        default_factory=list, description="Validated mental model IDs actually used in answer"
    )
-    used_observation_ids: list[str] = Field(
-        default_factory=list, description="Validated observation IDs actually used in answer"
-    )
    directives_applied: list[DirectiveInfo] = Field(
        default_factory=list, description="Directive mental models that affected this reflection"
    )
@@ -2,8 +2,8 @@
 System prompts for the reflect agent.

 The reflect agent uses hierarchical retrieval:
-1. search_mental_models - User-curated summaries (highest quality)
-2. search_observations - Consolidated knowledge with freshness awareness
+1. search_reflections - User-curated summaries (highest quality)
+2. search_mental_models - Consolidated knowledge with freshness awareness
 3. recall - Raw facts as ground truth fallback
 """

@@ -125,38 +125,28 @@ def build_system_prompt_for_tools(
    bank_profile: dict[str, Any],
    context: str | None = None,
    directives: list[dict[str, Any]] | None = None,
-    has_mental_models: bool = False,
-    budget: str | None = None,
+    has_reflections: bool = False,
 ) -> str:
    """
    Build the system prompt for tool-calling reflect agent.

    The agent uses hierarchical retrieval:
-    1. search_mental_models - User-curated summaries (try first, if available)
-    2. search_observations - Consolidated knowledge with freshness
+    1. search_reflections - User-curated summaries (try first, if available)
+    2. search_mental_models - Consolidated knowledge with freshness
    3. recall - Raw facts as ground truth

    Args:
        bank_profile: Bank profile with name and mission
        context: Optional additional context
        directives: Optional list of directive mental models to inject as hard rules
-        has_mental_models: Whether the bank has any mental models (skip if not)
-        budget: Search depth budget - "low", "mid", or "high". Controls exploration thoroughness.
+        has_reflections: Whether the bank has any reflections (skip if not)
    """
    name = bank_profile.get("name", "Assistant")
    mission = bank_profile.get("mission", "")

    parts = []

-    # Anti-hallucination rule at the very top
-    parts.extend(
-        [
-            "CRITICAL: You MUST ONLY use information from retrieved tool results. NEVER make up names, people, events, or entities.",
-            "",
-        ]
-    )
-
-    # Inject directives after anti-hallucination rule
+    # Inject directives at the VERY START for maximum prominence
    if directives:
        parts.append(build_directives_section(directives))

@@ -170,7 +160,7 @@ def build_system_prompt_for_tools(
    parts.extend(
        [
            "## CRITICAL RULES",
-            "- ONLY use information from tool results - no external knowledge or guessing",
+            "- You must NEVER fabricate information that has no basis in retrieved data",
            "- You SHOULD synthesize, infer, and reason from the retrieved memories",
            "- You MUST search before saying you don't have information",
            "",
@@ -186,25 +176,25 @@ def build_system_prompt_for_tools(
    )

    # Build retrieval levels based on what's available
-    if has_mental_models:
+    if has_reflections:
        parts.extend(
            [
                "You have access to THREE levels of knowledge. Use them in this order:",
                "",
-                "### 1. MENTAL MODELS (search_mental_models) - Try First",
+                "### 1. REFLECTIONS (search_reflections) - Try First",
                "- User-curated summaries about specific topics",
                "- HIGHEST quality - manually created and maintained",
-                "- If a relevant mental model exists and is FRESH, it may fully answer the question",
+                "- If a relevant reflection exists and is FRESH, it may fully answer the question",
                "- Check `is_stale` field - if stale, also verify with lower levels",
                "",
-                "### 2. OBSERVATIONS (search_observations) - Second Priority",
+                "### 2. MENTAL MODELS (search_mental_models) - Second Priority",
                "- Auto-consolidated knowledge from memories",
                "- Check `is_stale` field - if stale, ALSO use recall() to verify",
                "- Good for understanding patterns and summaries",
                "",
                "### 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",
+                "- Use when: no reflections/models exist, they're stale, or you need specific details",
                "- This is the source of truth that other levels are built from",
                "",
            ]
@@ -214,15 +204,15 @@ def build_system_prompt_for_tools(
            [
                "You have access to TWO levels of knowledge. Use them in this order:",
                "",
-                "### 1. OBSERVATIONS (search_observations) - Try First",
+                "### 1. MENTAL MODELS (search_mental_models) - Try First",
                "- Auto-consolidated knowledge from memories",
                "- Check `is_stale` field - if stale, ALSO use recall() to verify",
                "- Good for understanding patterns and summaries",
                "",
                "### 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",
-                "- This is the source of truth that observations are built from",
+                "- Use when: no mental models exist, they're stale, or you need specific details",
+                "- This is the source of truth that mental models are built from",
                "",
            ]
        )
@@ -240,57 +230,16 @@ def build_system_prompt_for_tools(
            "",
            "Think: What ENTITIES and CONCEPTS does this question involve? Search for each separately.",
            "",
+            "## Workflow",
        ]
    )

-    # Add budget guidance
-    if budget:
-        budget_lower = budget.lower()
-        if budget_lower == "low":
-            parts.extend(
-                [
-                    "## RESEARCH DEPTH: SHALLOW (Quick Response)",
-                    "- Prioritize speed over completeness",
-                    "- If mental models or observations provide a reasonable answer, stop there",
-                    "- Only dig deeper if the initial results are clearly insufficient",
-                    "- Prefer a quick overview rather than exhaustive details",
-                    "- Answer promptly with available information",
-                    "",
-                ]
-            )
-        elif budget_lower == "mid":
-            parts.extend(
-                [
-                    "## RESEARCH DEPTH: MODERATE (Balanced)",
-                    "- Balance thoroughness with efficiency",
-                    "- Check multiple sources when the question warrants it",
-                    "- Verify stale data if it's central to the answer",
-                    "- Don't over-explore, but ensure reasonable coverage",
-                    "",
-                ]
-            )
-        elif budget_lower == "high":
-            parts.extend(
-                [
-                    "## RESEARCH DEPTH: DEEP (Thorough Exploration)",
-                    "- Explore comprehensively before answering",
-                    "- Search across all available knowledge levels",
-                    "- Use multiple query variations to ensure coverage",
-                    "- Verify information across different retrieval levels",
-                    "- Use expand() to get full context on important memories",
-                    "- Take time to synthesize a complete, well-researched answer",
-                    "",
-                ]
-            )
-
-    parts.append("## Workflow")
-
-    if has_mental_models:
+    if has_reflections:
        parts.extend(
            [
-                "1. First, try search_mental_models() - check if a curated summary exists",
-                "2. If no mental model or it's stale, try search_observations() for consolidated knowledge",
-                "3. If observations are stale OR you need specific details, use recall() for raw facts",
+                "1. First, try search_reflections() - check if a curated summary exists",
+                "2. If no reflection or it's stale, try search_mental_models() for consolidated knowledge",
+                "3. If mental models are stale OR you need specific details, use recall() for raw facts",
                "4. Use expand() if you need more context on specific memories",
                "5. When ready, call done() with your answer and supporting IDs",
            ]
@@ -298,8 +247,8 @@ def build_system_prompt_for_tools(
    else:
        parts.extend(
            [
-                "1. First, try search_observations() - check for consolidated knowledge",
-                "2. If observations are stale OR you need specific details, use recall() for raw facts",
+                "1. First, try search_mental_models() - check for consolidated knowledge",
+                "2. If mental models 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",
            ]
@@ -308,13 +257,11 @@ def build_system_prompt_for_tools(
    parts.extend(
        [
            "",
-            "## Output Format: Well-Formatted Markdown Answer",
-            "Call done() with a well-formatted markdown 'answer' field.",
-            "- USE markdown formatting for structure (headers, lists, bold, italic, code blocks, tables, etc.)",
-            "- CRITICAL: Add blank lines before and after block elements (tables, code blocks, lists)",
-            "- Format for clarity and readability with proper spacing and hierarchy",
+            "## Output Format: Plain Text Answer",
+            "Call done() with a plain text 'answer' field.",
+            "- Do NOT use markdown formatting",
            "- 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",
+            "- Put IDs ONLY in the memory_ids/reflection_ids/mental_model_ids arrays, not in the answer",
        ]
    )

@@ -409,8 +356,8 @@ def build_agent_prompt(
        parts.append(
            "\n## Instructions\n"
            "Start by searching for relevant information using the hierarchical retrieval strategy:\n"
-            "1. Try search_mental_models() first for curated summaries\n"
-            "2. Try search_observations() for consolidated knowledge\n"
+            "1. Try search_reflections() first for curated summaries\n"
+            "2. Try search_mental_models() for consolidated knowledge\n"
            "3. Use recall() for specific details or to verify stale data"
        )

@@ -473,41 +420,21 @@ def build_final_prompt(
    parts.append(
        "\n## Instructions\n"
        "Provide a thoughtful answer by synthesizing and reasoning from the retrieved data above. "
-        "You can make reasonable inferences from the memories, but don't completely fabricate information. "
+        "You can make reasonable inferences from the memories, but don't completely fabricate information."
        "If the exact answer isn't stated, use what IS stated to give the best possible answer. "
-        "Only say 'I don't have information' if the retrieved data is truly unrelated to the question.\n\n"
-        "IMPORTANT: Output ONLY the final answer. Do NOT include meta-commentary like "
-        '"I\'ll search..." or "Let me analyze...". Do NOT explain your reasoning process. '
-        "Just provide the direct synthesized answer."
+        "Only say 'I don't have information' if the retrieved data is truly unrelated to the question."
    )

    return "\n".join(parts)


-FINAL_SYSTEM_PROMPT = """CRITICAL: You MUST ONLY use information from retrieved tool results. NEVER make up names, people, events, or entities.
-
-You are a thoughtful assistant that synthesizes answers from retrieved memories.
+FINAL_SYSTEM_PROMPT = """You are a thoughtful assistant that synthesizes answers from retrieved memories.

 Your approach:
 - Reason over the retrieved memories to answer the question
 - Make reasonable inferences when the exact answer isn't explicitly stated
 - Connect related memories to form a complete picture
 - Be helpful - if you have related information, use it to give the best possible answer
- ONLY use information from tool results - no external knowledge or guessing

 Only say "I don't have information" if the retrieved data is truly unrelated to the question.
-
-FORMATTING: Use proper markdown formatting in your answer:
- Headers (##, ###) for sections
- Lists (bullet or numbered) for enumerations
- Bold/italic for emphasis
- Tables with proper syntax (ensure blank line before and after)
- Code blocks where appropriate
- CRITICAL: Always add blank lines before and after block elements (tables, code blocks, lists)
- Proper spacing between sections
-
-CRITICAL: Output ONLY the final synthesized answer. Do NOT include:
- Meta-commentary about what you're doing ("I'll search...", "Let me analyze...")
- Explanations of your reasoning process
- Descriptions of your approach
-Just provide the direct answer with proper markdown formatting."""
+Do NOT fabricate information that has no basis in the retrieved data."""
@@ -2,8 +2,8 @@
 Tool implementations for the reflect agent.

 Implements hierarchical retrieval:
-1. search_mental_models - User-curated stored reflect responses (highest quality)
-2. search_observations - Consolidated knowledge with freshness
+1. search_reflections - User-curated summaries (highest quality)
+2. search_mental_models - Consolidated knowledge with freshness
 3. recall - Raw facts as ground truth
 """

@@ -20,11 +20,11 @@ if TYPE_CHECKING:

 logger = logging.getLogger(__name__)

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


-async def tool_search_mental_models(
+async def tool_search_reflections(
    conn: "Connection",
    bank_id: str,
    query: str,
@@ -35,9 +35,9 @@ async def tool_search_mental_models(
    exclude_ids: list[str] | None = None,
 ) -> dict[str, Any]:
    """
-    Search user-curated mental models by semantic similarity.
+    Search user-curated reflections by semantic similarity.

-    Mental models are high-quality, manually created summaries about specific topics.
+    Reflections are high-quality, manually created summaries about specific topics.
    They should be searched FIRST as they represent the most reliable synthesized knowledge.

    Args:
@@ -45,41 +45,42 @@ async def tool_search_mental_models(
        bank_id: Bank identifier
        query: Search query (for logging/tracing)
        query_embedding: Pre-computed embedding for semantic search
-        max_results: Maximum number of mental models to return
-        tags: Optional tags to filter mental models
+        max_results: Maximum number of reflections to return
+        tags: Optional tags to filter reflections
        tags_match: How to match tags - "any" (OR), "all" (AND)
-        exclude_ids: Optional list of mental model IDs to exclude (e.g., when refreshing a mental model)
+        exclude_ids: Optional list of reflection IDs to exclude (e.g., when refreshing a reflection)

    Returns:
-        Dict with matching mental models including content and freshness info
+        Dict with matching reflections including content and freshness info
    """
    from ..memory_engine import fq_table
-    from ..search.tags import build_tags_where_clause

    # Build filters dynamically
    filters = ""
    params: list[Any] = [bank_id, str(query_embedding), max_results]
    next_param = 4

-    # Use the centralized tag filtering logic
    if tags:
-        tag_clause, tag_params, next_param = build_tags_where_clause(tags, param_offset=next_param, match=tags_match)
-        filters += f" {tag_clause}"
-        params.extend(tag_params)
+        if tags_match == "all":
+            filters += f" AND tags @> ${next_param}::varchar[]"
+        else:
+            filters += f" AND (tags && ${next_param}::varchar[] OR tags IS NULL OR tags = '{{}}')"
+        params.append(tags)
+        next_param += 1

    if exclude_ids:
-        filters += f" AND id != ALL(${next_param}::text[])"
+        filters += f" AND id != ALL(${next_param}::uuid[])"
        params.append(exclude_ids)
        next_param += 1

-    # Search mental models by embedding similarity
+    # Search reflections by embedding similarity
    rows = await conn.fetch(
        f"""
        SELECT
-            id, name, content,
+            id, name, content, reflect_response,
            tags, created_at, last_refreshed_at,
            1 - (embedding <=> $2::vector) as relevance
-        FROM {fq_table("mental_models")}
+        FROM {fq_table("reflections")}
        WHERE bank_id = $1 AND embedding IS NOT NULL {filters}
        ORDER BY embedding <=> $2::vector
        LIMIT $3
@@ -88,7 +89,7 @@ async def tool_search_mental_models(
    )

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

    for row in rows:
        last_refreshed_at = row["last_refreshed_at"]
@@ -101,11 +102,12 @@ async def tool_search_mental_models(
            age = now - last_refreshed_at
            is_stale = age > timedelta(days=STALE_THRESHOLD_DAYS)

-        mental_models.append(
+        reflections.append(
            {
                "id": str(row["id"]),
                "name": row["name"],
                "content": row["content"],
+                "reflect_response": row["reflect_response"],
                "tags": row["tags"] or [],
                "relevance": round(row["relevance"], 4),
                "updated_at": last_refreshed_at.isoformat() if last_refreshed_at else None,
@@ -115,12 +117,12 @@ async def tool_search_mental_models(

    return {
        "query": query,
-        "count": len(mental_models),
-        "mental_models": mental_models,
+        "count": len(reflections),
+        "reflections": reflections,
    }


-async def tool_search_observations(
+async def tool_search_mental_models(
    memory_engine: "MemoryEngine",
    bank_id: str,
    query: str,
@@ -132,9 +134,9 @@ async def tool_search_observations(
    pending_consolidation: int = 0,
 ) -> dict[str, Any]:
    """
-    Search consolidated observations using recall with include_observations.
+    Search consolidated mental models using recall with include_mental_models.

-    Observations are auto-generated from memories. Returns freshness info
+    Mental models are auto-generated from memories. Returns freshness info
    so the agent knows if it should also verify with recall().

    Args:
@@ -143,22 +145,22 @@ async def tool_search_observations(
        query: Search query
        request_context: Request context for authentication
        max_tokens: Maximum tokens for results (default 5000)
-        tags: Optional tags to filter observations
+        tags: Optional tags to filter models
        tags_match: How to match tags - "any" (OR), "all" (AND)
        last_consolidated_at: When consolidation last ran (for staleness check)
        pending_consolidation: Number of memories waiting to be consolidated

    Returns:
-        Dict with matching observations including freshness info
+        Dict with matching mental models including freshness info
    """
    from ..memory_engine import fq_table

-    # Use recall to search observations (they come back in results field when fact_type=["observation"])
+    # Use recall to search mental models (they come back in results field when fact_type=["mental_model"])
    result = await memory_engine.recall_async(
        bank_id=bank_id,
        query=query,
-        fact_type=["observation"],  # Only retrieve observations
-        max_tokens=max_tokens,  # Token budget controls how many observations are returned
+        fact_type=["mental_model"],  # Only retrieve mental models
+        max_tokens=max_tokens,  # Token budget controls how many mental models are returned
        enable_trace=False,
        request_context=request_context,
        tags=tags,
@@ -167,29 +169,29 @@ async def tool_search_observations(
        _quiet=True,
    )

-    observations = []
+    mental_models = []

-    # When fact_type=["observation"], results come back in `results` field as MemoryFact objects
+    # When fact_type=["mental_model"], 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]
+        mm_ids = [m.id for m in result.results]

-        # Fetch proof_count and source_memory_ids for these observations
+        # Fetch proof_count and source_memory_ids for these mental models
        pool = await memory_engine._get_pool()
        async with pool.acquire() as conn:
-            obs_rows = await conn.fetch(
+            mm_rows = await conn.fetch(
                f"""
                SELECT id, proof_count, source_memory_ids
                FROM {fq_table("memory_units")}
                WHERE id = ANY($1::uuid[])
                """,
-                obs_ids,
+                mm_ids,
            )
-            obs_data = {str(row["id"]): row for row in obs_rows}
+            mm_data = {str(row["id"]): row for row in mm_rows}

        for m in result.results:
            # Get additional data from DB lookup
-            extra = obs_data.get(m.id, {})
+            extra = mm_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
@@ -202,7 +204,7 @@ async def tool_search_observations(
                is_stale = True
                staleness_reason = f"{pending_consolidation} memories pending consolidation"

-            observations.append(
+            mental_models.append(
                {
                    "id": str(m.id),
                    "text": m.text,
@@ -224,8 +226,8 @@ async def tool_search_observations(

    return {
        "query": query,
-        "count": len(observations),
-        "observations": observations,
+        "count": len(mental_models),
+        "mental_models": mental_models,
        "freshness": freshness,
    }

@@ -245,7 +247,7 @@ async def tool_recall(
    Search memories using TEMPR retrieval.

    This is the ground truth - raw facts and experiences.
-    Use when mental models/observations don't exist, are stale, or need verification.
+    Use when reflections/mental models don't exist, are stale, or need verification.

    Args:
        memory_engine: Memory engine instance
@@ -264,7 +266,7 @@ async def tool_recall(
    result = await memory_engine.recall_async(
        bank_id=bank_id,
        query=query,
-        fact_type=["experience", "world"],  # Exclude opinions and observations
+        fact_type=["experience", "world"],  # Exclude opinions and mental_models
        max_tokens=max_tokens,
        enable_trace=False,
        request_context=request_context,
@@ -3,69 +3,61 @@ Tool schema definitions for the reflect agent.

 These are OpenAI-format tool definitions used with native tool calling.
 The reflect agent uses a hierarchical retrieval strategy:
-1. search_mental_models - User-curated stored reflect responses (highest quality, if applicable)
-2. search_observations - Consolidated knowledge with freshness awareness
+1. search_reflections - User-curated summaries (highest quality, if applicable)
+2. search_mental_models - Consolidated knowledge with freshness awareness
 3. recall - Raw facts (world/experience) as ground truth fallback
 """

 # Tool definitions in OpenAI format

+TOOL_SEARCH_REFLECTIONS = {
+    "type": "function",
+    "function": {
+        "name": "search_reflections",
+        "description": (
+            "Search user-curated reflections (summaries). These are high-quality, manually created "
+            "summaries about specific topics. Use FIRST when the question might be covered by an "
+            "existing reflection. Returns reflections with their content and last refresh time."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query to find relevant reflections",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of reflections to return (default 5)",
+                },
+            },
+            "required": ["query"],
+        },
+    },
+}
+
 TOOL_SEARCH_MENTAL_MODELS = {
    "type": "function",
    "function": {
        "name": "search_mental_models",
        "description": (
-            "Search user-curated mental models (stored reflect responses). These are high-quality, manually created "
-            "summaries about specific topics. Use FIRST when the question might be covered by an "
-            "existing mental model. Returns mental models with their content and last refresh time."
+            "Search consolidated mental models (auto-generated knowledge). These are automatically "
+            "synthesized from memories. Returns models with freshness info (updated_at, is_stale). "
+            "If a model is STALE, you should ALSO use recall() to verify with current facts."
        ),
        "parameters": {
            "type": "object",
            "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you're making this search (for debugging)",
-                },
                "query": {
                    "type": "string",
                    "description": "Search query to find relevant mental models",
                },
-                "max_results": {
-                    "type": "integer",
-                    "description": "Maximum number of mental models to return (default 5)",
-                },
-            },
-            "required": ["reason", "query"],
-        },
-    },
-}
-
-TOOL_SEARCH_OBSERVATIONS = {
-    "type": "function",
-    "function": {
-        "name": "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."
-        ),
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you're making this search (for debugging)",
-                },
-                "query": {
-                    "type": "string",
-                    "description": "Search query to find relevant observations",
-                },
                "max_tokens": {
                    "type": "integer",
                    "description": "Maximum tokens for results (default 5000). Use higher values for broader searches.",
                },
            },
-            "required": ["reason", "query"],
+            "required": ["query"],
        },
    },
 }
@@ -83,10 +75,6 @@ TOOL_RECALL = {
        "parameters": {
            "type": "object",
            "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you're making this search (for debugging)",
-                },
                "query": {
                    "type": "string",
                    "description": "Search query string",
@@ -96,7 +84,7 @@ TOOL_RECALL = {
                    "description": "Optional limit on result size (default 2048). Use higher values for broader searches.",
                },
            },
-            "required": ["reason", "query"],
+            "required": ["query"],
        },
    },
 }
@@ -109,10 +97,6 @@ TOOL_EXPAND = {
        "parameters": {
            "type": "object",
            "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you need more context (for debugging)",
-                },
                "memory_ids": {
                    "type": "array",
                    "items": {"type": "string"},
@@ -124,7 +108,7 @@ TOOL_EXPAND = {
                    "description": "chunk: surrounding text chunk, document: full source document",
                },
            },
-            "required": ["reason", "memory_ids", "depth"],
+            "required": ["memory_ids", "depth"],
        },
    },
 }
@@ -139,23 +123,23 @@ 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.",
+                    "description": "Your response as plain text. Do NOT use markdown formatting. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
                },
                "memory_ids": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
                },
+                "reflection_ids": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Array of reflection IDs that support your answer",
+                },
                "mental_model_ids": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Array of mental model IDs that support your answer",
                },
-                "observation_ids": {
-                    "type": "array",
-                    "items": {"type": "string"},
-                    "description": "Array of observation IDs that support your answer",
-                },
            },
            "required": ["answer"],
        },
@@ -190,23 +174,23 @@ 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.",
+                        "description": "Your response as plain text. Do NOT use markdown formatting. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
                    },
                    "memory_ids": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
                    },
+                    "reflection_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Array of reflection IDs that support your answer",
+                    },
                    "mental_model_ids": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Array of mental model IDs that support your answer",
                    },
-                    "observation_ids": {
-                        "type": "array",
-                        "items": {"type": "string"},
-                        "description": "Array of observation IDs that support your answer",
-                    },
                    "directive_compliance": {
                        "type": "string",
                        "description": f"REQUIRED: Confirm your answer complies with ALL directives. List each directive and how your answer follows it:\n{rules_list}\n\nFormat: 'Directive 1: [how answer complies]. Directive 2: [how answer complies]...'",
@@ -223,8 +207,8 @@ def get_reflect_tools(directive_rules: list[str] | None = None) -> list[dict]:
    Get the list of tools for the reflect agent.

    The tools support a hierarchical retrieval strategy:
-    1. search_mental_models - User-curated stored reflect responses (try first)
-    2. search_observations - Consolidated knowledge with freshness
+    1. search_reflections - User-curated summaries (try first)
+    2. search_mental_models - Consolidated knowledge with freshness
    3. recall - Raw facts as ground truth

    Args:
@@ -235,8 +219,8 @@ def get_reflect_tools(directive_rules: list[str] | None = None) -> list[dict]:
        List of tool definitions in OpenAI format
    """
    tools = [
+        TOOL_SEARCH_REFLECTIONS,
        TOOL_SEARCH_MENTAL_MODELS,
-        TOOL_SEARCH_OBSERVATIONS,
        TOOL_RECALL,
        TOOL_EXPAND,
    ]
@@ -10,8 +10,8 @@ from typing import Any

 from pydantic import BaseModel, ConfigDict, Field

-# Valid fact types for recall operations (excludes 'opinion' which is deprecated)
-VALID_RECALL_FACT_TYPES = frozenset(["world", "experience", "observation"])
+# Valid fact types for recall operations (excludes 'observation' which is internal, and 'opinion' which is deprecated)
+VALID_RECALL_FACT_TYPES = frozenset(["world", "experience", "mental_model"])


 class LLMToolCall(BaseModel):
@@ -36,7 +36,6 @@ class ToolCallTrace(BaseModel):
    """A single tool call made during reflect."""

    tool: str = Field(description="Tool name: lookup, recall, learn, expand")
-    reason: str | None = Field(default=None, description="Agent's reasoning for making this tool call")
    input: dict = Field(description="Tool input parameters")
    output: dict = Field(description="Tool output/result")
    duration_ms: int = Field(description="Execution time in milliseconds")
@@ -50,13 +49,13 @@ class LLMCallTrace(BaseModel):
    duration_ms: int = Field(description="Execution time in milliseconds")


-class ObservationRef(BaseModel):
-    """Reference to an observation accessed during reflect."""
+class MentalModelRef(BaseModel):
+    """Reference to a mental model accessed during reflect."""

-    id: str = Field(description="Observation ID")
-    name: str = Field(description="Observation name")
-    type: str = Field(description="Observation type: entity, concept, event")
-    subtype: str = Field(description="Observation subtype: structural, emergent, learned")
+    id: str = Field(description="Mental model ID")
+    name: str = Field(description="Mental model name")
+    type: str = Field(description="Mental model type: entity, concept, event")
+    subtype: str = Field(description="Mental model subtype: structural, emergent, learned")
    description: str = Field(description="Brief description")
    summary: str | None = Field(default=None, description="Full summary (when looked up in detail)")

@@ -66,7 +65,7 @@ class DirectiveRef(BaseModel):

    id: str = Field(description="Directive mental model ID")
    name: str = Field(description="Directive name")
-    content: str = Field(description="Directive content")
+    rules: list[str] = Field(default_factory=list, description="Directive rules/observations that were applied")


 class TokenUsage(BaseModel):
@@ -169,23 +168,23 @@ class ChunkInfo(BaseModel):
    truncated: bool = Field(default=False, description="Whether the chunk was truncated due to token limits")


-class ObservationResult(BaseModel):
-    """An observation result from recall (consolidated knowledge synthesized from facts)."""
+class MentalModelResult(BaseModel):
+    """A mental model result from recall."""

-    id: str = Field(description="Unique observation ID")
-    text: str = Field(description="The observation text")
-    proof_count: int = Field(description="Number of facts supporting this observation")
+    id: str = Field(description="Unique mental model ID")
+    text: str = Field(description="The mental model text")
+    proof_count: int = Field(description="Number of facts supporting this mental model")
    relevance: float = Field(default=0.0, description="Relevance score to the query")
    tags: list[str] | None = Field(default=None, description="Tags for visibility scoping")
    source_memory_ids: list[str] = Field(
-        default_factory=list, description="IDs of facts that contribute to this observation"
+        default_factory=list, description="IDs of facts that contribute to this mental model"
    )


-class MentalModelResult(BaseModel):
-    """A mental model result from recall (stored reflect response)."""
+class ReflectionResult(BaseModel):
+    """A reflection result from recall."""

-    id: str = Field(description="Unique mental model ID")
+    id: str = Field(description="Unique reflection ID")
    name: str = Field(description="Human-readable name")
    content: str = Field(description="The synthesized content")
    relevance: float = Field(default=0.0, description="Relevance score to the query")
@@ -254,15 +253,9 @@ class ReflectResult(BaseModel):
                    ],
                    "experience": [],
                    "opinion": [],
-                    "mental_models": [],
-                    "directives": [
-                        {
-                            "id": "directive-123",
-                            "name": "Response Style",
-                            "rules": ["Always be concise"],
-                        }
-                    ],
+                    "mental-models": [],
                },
+                "new_opinions": ["Machine learning has great potential in healthcare"],
                "structured_output": {"summary": "ML in healthcare", "confidence": 0.9},
                "usage": {"input_tokens": 1500, "output_tokens": 500, "total_tokens": 2000},
            }
@@ -270,9 +263,10 @@ class ReflectResult(BaseModel):
    )

    text: str = Field(description="The formulated answer text")
-    based_on: dict[str, Any] = Field(
-        description="Facts used to formulate the answer, organized by type (world, experience, mental_models, directives)"
+    based_on: dict[str, list[MemoryFact]] = Field(
+        description="Facts used to formulate the answer, organized by type (world, experience, opinion, mental-models)"
    )
+    new_opinions: list[str] = Field(default_factory=list, description="List of newly formed opinions during reflection")
    structured_output: dict[str, Any] | None = Field(
        default=None,
        description="Structured output parsed according to the provided response schema. Only present when response_schema was provided.",
@@ -295,6 +289,24 @@ class ReflectResult(BaseModel):
    )


+class Opinion(BaseModel):
+    """
+    An opinion with confidence score.
+
+    Opinions represent the bank's formed perspectives on topics,
+    with a confidence level indicating strength of belief.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {"text": "Machine learning has great potential in healthcare", "confidence": 0.85}
+        }
+    )
+
+    text: str = Field(description="The opinion text")
+    confidence: float = Field(description="Confidence score between 0.0 and 1.0")
+
+
 class EntityObservation(BaseModel):
    """
    An observation about an entity.
@@ -57,25 +57,21 @@ def _infer_temporal_date(fact_text: str, event_date: datetime) -> str | None:
    return None


-def _sanitize_text(text: str | None) -> str | None:
+def _sanitize_text(text: str) -> str:
    """
-    Sanitize text by removing characters that break downstream systems.
+    Sanitize text by removing invalid Unicode surrogate characters.

-    Removes:
-    - Null bytes (\\x00): Invalid in PostgreSQL UTF-8 encoding
-    - Unicode surrogates (U+D800-U+DFFF): Invalid in UTF-8, break LLM APIs
+    Surrogate characters (U+D800 to U+DFFF) are used in UTF-16 encoding
+    but cannot be encoded in UTF-8. They can appear in Python strings
+    from improperly decoded data (e.g., from JavaScript or broken files).

-    Surrogate characters are used in UTF-16 encoding but cannot be encoded
-    in UTF-8. They can appear in Python strings from improperly decoded data
-    (e.g., from JavaScript or broken files). Null bytes commonly appear in
-    OCR output, PDF extraction, or copy-paste from binary sources.
+    This function removes unpaired surrogates to prevent UnicodeEncodeError
+    when the text is sent to the LLM API.
    """
-    if text is None:
-        return None
    if not text:
        return text
-    # Remove null bytes and surrogate characters
-    text = text.replace("\x00", "")
+    # Remove surrogate characters (U+D800 to U+DFFF) using regex
+    # These are invalid in UTF-8 and cause encoding errors
    return re.sub(r"[\ud800-\udfff]", "", text)


@@ -436,15 +432,34 @@ def _chunk_conversation(turns: list[dict], max_chars: int) -> list[str]:
 # FACT EXTRACTION PROMPTS
 # =============================================================================

-# Base prompt template (shared by concise and custom modes)
-# Uses {extraction_guidelines} placeholder for mode-specific instructions
-_BASE_FACT_EXTRACTION_PROMPT = """Extract SIGNIFICANT facts from text. Be SELECTIVE - only extract facts worth remembering long-term.
+# Concise extraction prompt (default) - selective, high-quality facts
+CONCISE_FACT_EXTRACTION_PROMPT = """Extract SIGNIFICANT facts from text. Be SELECTIVE - only extract facts worth remembering long-term.

 LANGUAGE REQUIREMENT: Detect the language of the input text. All extracted facts, entity names, descriptions, and other output MUST be in the SAME language as the input. Do not translate to another language.

 {fact_types_instruction}

-{extraction_guidelines}
+══════════════════════════════════════════════════════════════════════════
+SELECTIVITY - CRITICAL (Reduces 90% of unnecessary output)
+══════════════════════════════════════════════════════════════════════════
+
+ONLY extract facts that are:
+✅ Personal info: names, relationships, roles, background
+✅ Preferences: likes, dislikes, habits, interests (e.g., "Alice likes coffee")
+✅ Significant events: milestones, decisions, achievements, changes
+✅ Plans/goals: future intentions, deadlines, commitments
+✅ Expertise: skills, knowledge, certifications, experience
+✅ Important context: projects, problems, constraints
+✅ Sensory/emotional details: feelings, sensations, perceptions that provide context
+✅ Observations: descriptions of people, places, things with specific details
+
+DO NOT extract:
+❌ Generic greetings: "how are you", "hello", pleasantries without substance
+❌ Pure filler: "thanks", "sounds good", "ok", "got it", "sure"
+❌ Process chatter: "let me check", "one moment", "I'll look into it"
+❌ Repeated info: if already stated, don't extract again
+
+CONSOLIDATE related statements into ONE fact when possible.

 ══════════════════════════════════════════════════════════════════════════
 FACT FORMAT - BE CONCISE
@@ -492,33 +507,7 @@ ENTITIES
 ══════════════════════════════════════════════════════════════════════════

 Include: people names, organizations, places, key objects, abstract concepts (career, friendship, etc.)
-Always include "user" when fact is about the user.{examples}"""
-
-# Concise mode guidelines
-_CONCISE_GUIDELINES = """══════════════════════════════════════════════════════════════════════════
-SELECTIVITY - CRITICAL (Reduces 90% of unnecessary output)
-══════════════════════════════════════════════════════════════════════════
-
-ONLY extract facts that are:
-✅ Personal info: names, relationships, roles, background
-✅ Preferences: likes, dislikes, habits, interests (e.g., "Alice likes coffee")
-✅ Significant events: milestones, decisions, achievements, changes
-✅ Plans/goals: future intentions, deadlines, commitments
-✅ Expertise: skills, knowledge, certifications, experience
-✅ Important context: projects, problems, constraints
-✅ Sensory/emotional details: feelings, sensations, perceptions that provide context
-✅ Observations: descriptions of people, places, things with specific details
-
-DO NOT extract:
-❌ Generic greetings: "how are you", "hello", pleasantries without substance
-❌ Pure filler: "thanks", "sounds good", "ok", "got it", "sure"
-❌ Process chatter: "let me check", "one moment", "I'll look into it"
-❌ Repeated info: if already stated, don't extract again
-
-CONSOLIDATE related statements into ONE fact when possible."""
-
-# Concise mode examples
-_CONCISE_EXAMPLES = """
+Always include "user" when fact is about the user.

 ══════════════════════════════════════════════════════════════════════════
 EXAMPLES
@@ -542,26 +531,7 @@ Output: ONLY 2 facts (skip coffee preference - too trivial):
 QUALITY OVER QUANTITY
 ══════════════════════════════════════════════════════════════════════════

-Ask: "Would this be useful to recall in 6 months?" If no, skip it.
-
-IMPORTANT: Sensory/emotional details and observations that provide meaningful context
-about experiences ARE important to remember, even if they seem small (e.g., how food
-tasted, how someone looked, how loud music was). Extract these if they characterize
-an experience or person."""
-
-# Assembled concise prompt (backward compatible - exact same output as before)
-CONCISE_FACT_EXTRACTION_PROMPT = _BASE_FACT_EXTRACTION_PROMPT.format(
-    fact_types_instruction="{fact_types_instruction}",
-    extraction_guidelines=_CONCISE_GUIDELINES,
-    examples=_CONCISE_EXAMPLES,
-)
-
-# Custom prompt uses same base but without examples
-CUSTOM_FACT_EXTRACTION_PROMPT = _BASE_FACT_EXTRACTION_PROMPT.format(
-    fact_types_instruction="{fact_types_instruction}",
-    extraction_guidelines="{custom_instructions}",
-    examples="",  # No examples for custom mode
-)
+Ask: "Would this be useful to recall in 6 months?" If no, skip it."""


 # Verbose extraction prompt - detailed, comprehensive facts (legacy mode)
@@ -646,7 +616,6 @@ For EVENTS (fact_kind="event") - MUST SET BOTH occurred_start AND occurred_end:
 - Convert relative dates → absolute using Event Date as reference
 - If Event Date is "Saturday, March 15, 2020", then "yesterday" = Friday, March 14, 2020
 - Dates mentioned in text (e.g., "in March 2020") should use THAT year, not current year
- CRITICAL: If the content mentions an absolute date (e.g., "March 15, 2024", "2024-03-15"), you MUST extract it and set occurred_start in ISO format
 - Always include the day name (Monday, Tuesday, etc.) in the 'when' field
 - Set occurred_start AND occurred_end to WHEN IT HAPPENED (not when mentioned)
 - For single-day/point events: set occurred_end = occurred_start (same timestamp)
@@ -703,6 +672,7 @@ async def _extract_facts_from_chunk(
    context: str,
    llm_config: "LLMConfig",
    agent_name: str = None,
+    extract_opinions: bool = False,
 ) -> tuple[list[dict[str, str]], TokenUsage]:
    """
    Extract facts from a single chunk (internal helper for parallel processing).
@@ -710,15 +680,17 @@ async def _extract_facts_from_chunk(
    Note: event_date parameter is kept for backward compatibility but not used in prompt.
    The LLM extracts temporal information from the context string instead.
    """
-    import logging
+    memory_bank_context = f"\n- Your name: {agent_name}" if agent_name and extract_opinions else ""

-    from openai import BadRequestError
-
-    logger = logging.getLogger(__name__)
-
-    # Determine which fact types to extract
+    # Determine which fact types to extract based on the flag
    # Note: We use "assistant" in the prompt but convert to "bank" for storage
-    fact_types_instruction = "Extract ONLY 'world' and 'assistant' type facts."
+    if extract_opinions:
+        # Opinion extraction uses a separate prompt (not this one)
+        fact_types_instruction = "Extract ONLY 'opinion' type facts (formed opinions, beliefs, and perspectives). DO NOT extract 'world' or 'assistant' facts."
+    else:
+        fact_types_instruction = (
+            "Extract ONLY 'world' and 'assistant' type facts. DO NOT extract opinions - those are extracted separately."
+        )

    # Check config for extraction mode and causal link extraction
    config = get_config()
@@ -726,27 +698,13 @@ async def _extract_facts_from_chunk(
    extract_causal_links = config.retain_extract_causal_links

    # Select base prompt based on extraction mode
-    if extraction_mode == "custom":
-        # Custom mode: inject user-provided guidelines
-        if not config.retain_custom_instructions:
-            logger.warning(
-                "extraction_mode='custom' but HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS not set. "
-                "Falling back to 'concise' mode."
-            )
-            base_prompt = CONCISE_FACT_EXTRACTION_PROMPT
-            prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
-        else:
-            base_prompt = CUSTOM_FACT_EXTRACTION_PROMPT
-            prompt = base_prompt.format(
-                fact_types_instruction=fact_types_instruction,
-                custom_instructions=config.retain_custom_instructions,
-            )
-    elif extraction_mode == "verbose":
+    if extraction_mode == "verbose":
        base_prompt = VERBOSE_FACT_EXTRACTION_PROMPT
-        prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
    else:
        base_prompt = CONCISE_FACT_EXTRACTION_PROMPT
-        prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
+
+    # Format the prompt with fact types instruction
+    prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)

    # Build the full prompt with or without causal relationships section
    # Select appropriate response schema based on extraction mode and causal links
@@ -759,6 +717,12 @@ async def _extract_facts_from_chunk(
    else:
        response_schema = FactExtractionResponseNoCausal

+    import logging
+
+    from openai import BadRequestError
+
+    logger = logging.getLogger(__name__)
+
    # Retry logic for JSON validation errors
    max_retries = 2
    last_error = None
@@ -769,12 +733,9 @@ async def _extract_facts_from_chunk(

    # Build user message with metadata and chunk content in a clear format
    # Format event_date with day of week for better temporal reasoning
-    # Handle both datetime objects and ISO string formats (from deserialized async tasks)
-    from .orchestrator import parse_datetime_flexible
-
-    event_date = parse_datetime_flexible(event_date)
    event_date_formatted = event_date.strftime("%A, %B %d, %Y")  # e.g., "Monday, June 10, 2024"
    user_message = f"""Extract facts from the following text chunk.
+{memory_bank_context}

 Chunk: {chunk_index + 1}/{total_chunks}
 Event Date: {event_date_formatted} ({event_date.isoformat()})
@@ -786,28 +747,12 @@ Text:
    usage = TokenUsage()  # Track cumulative usage across retries
    for attempt in range(max_retries):
        try:
-            # Use retain-specific overrides if set, otherwise fall back to global LLM config
-            max_retries = (
-                config.retain_llm_max_retries if config.retain_llm_max_retries is not None else config.llm_max_retries
-            )
-            initial_backoff = (
-                config.retain_llm_initial_backoff
-                if config.retain_llm_initial_backoff is not None
-                else config.llm_initial_backoff
-            )
-            max_backoff = (
-                config.retain_llm_max_backoff if config.retain_llm_max_backoff is not None else config.llm_max_backoff
-            )
-
            extraction_response_json, call_usage = await llm_config.call(
                messages=[{"role": "system", "content": prompt}, {"role": "user", "content": user_message}],
                response_format=response_schema,
-                scope="retain_extract_facts",
+                scope="memory_extract_facts",
                temperature=0.1,
                max_completion_tokens=config.retain_max_completion_tokens,
-                max_retries=max_retries,
-                initial_backoff=initial_backoff,
-                max_backoff=max_backoff,
                skip_validation=True,  # Get raw JSON, we'll validate leniently
                return_usage=True,
            )
@@ -1011,29 +956,6 @@ Text:

        except BadRequestError as e:
            last_error = e
-            error_str = str(e).lower()
-
-            # Check if error is related to max_tokens/completion_tokens not being supported
-            if any(
-                keyword in error_str
-                for keyword in [
-                    "max_tokens",
-                    "max_completion_tokens",
-                    "maximum context",
-                    "token limit",
-                    "context length",
-                ]
-            ):
-                # Provide helpful error message with configuration suggestions
-                raise ValueError(
-                    f"Model does not support the required output token limit.\n\n"
-                    f"The model '{llm_config.model}' (provider: {llm_config.provider}) failed with: {e}\n\n"
-                    f"You have two options to fix this:\n"
-                    f"  1. Use a different model that supports at least {config.retain_max_completion_tokens} output tokens\n"
-                    f"  2. Decrease HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS to a value your model supports\n"
-                    f"     (current value: {config.retain_max_completion_tokens}, must be > RETAIN_CHUNK_SIZE={config.retain_chunk_size})"
-                ) from e
-
            if "json_validate_failed" in str(e):
                logger.warning(
                    f"          [1.3.{chunk_index + 1}] Attempt {attempt + 1}/{max_retries} failed with JSON validation error: {e}"
@@ -1056,6 +978,7 @@ async def _extract_facts_with_auto_split(
    context: str,
    llm_config: LLMConfig,
    agent_name: str = None,
+    extract_opinions: bool = False,
 ) -> tuple[list[dict[str, str]], TokenUsage]:
    """
    Extract facts from a chunk with automatic splitting if output exceeds token limits.
@@ -1071,6 +994,7 @@ async def _extract_facts_with_auto_split(
        context: Context about the conversation/document
        llm_config: LLM configuration to use
        agent_name: Optional agent name (memory owner)
+        extract_opinions: If True, extract ONLY opinions. If False, extract world and agent facts (no opinions)

    Returns:
        Tuple of (facts list, token usage) extracted from the chunk (possibly from sub-chunks)
@@ -1089,6 +1013,7 @@ async def _extract_facts_with_auto_split(
            context=context,
            llm_config=llm_config,
            agent_name=agent_name,
+            extract_opinions=extract_opinions,
        )
    except OutputTooLongError:
        # Output exceeded token limits - split the chunk in half and retry
@@ -1133,6 +1058,7 @@ async def _extract_facts_with_auto_split(
                context=context,
                llm_config=llm_config,
                agent_name=agent_name,
+                extract_opinions=extract_opinions,
            ),
            _extract_facts_with_auto_split(
                chunk=second_half,
@@ -1142,6 +1068,7 @@ async def _extract_facts_with_auto_split(
                context=context,
                llm_config=llm_config,
                agent_name=agent_name,
+                extract_opinions=extract_opinions,
            ),
        ]

@@ -1165,6 +1092,7 @@ async def extract_facts_from_text(
    llm_config: LLMConfig,
    agent_name: str,
    context: str = "",
+    extract_opinions: bool = False,
 ) -> tuple[list[Fact], list[tuple[str, int]], TokenUsage]:
    """
    Extract semantic facts from conversational or narrative text using LLM.
@@ -1181,6 +1109,7 @@ async def extract_facts_from_text(
        context: Context about the conversation/document
        llm_config: LLM configuration to use
        agent_name: Agent name (memory owner)
+        extract_opinions: If True, extract ONLY opinions. If False, extract world and bank facts (no opinions)

    Returns:
        Tuple of (facts, chunks, usage) where:
@@ -1208,6 +1137,7 @@ async def extract_facts_from_text(
            context=context,
            llm_config=llm_config,
            agent_name=agent_name,
+            extract_opinions=extract_opinions,
        )
        for i, chunk in enumerate(chunks)
    ]
@@ -1239,7 +1169,7 @@ SECONDS_PER_FACT = 10


 async def extract_facts_from_contents(
-    contents: list[RetainContent], llm_config, agent_name: str
+    contents: list[RetainContent], llm_config, agent_name: str, extract_opinions: bool = False
 ) -> tuple[list[ExtractedFactType], list[ChunkMetadata], TokenUsage]:
    """
    Extract facts from multiple content items in parallel.
@@ -1254,6 +1184,7 @@ async def extract_facts_from_contents(
        contents: List of RetainContent objects to process
        llm_config: LLM configuration for fact extraction
        agent_name: Name of the agent (for agent-related fact detection)
+        extract_opinions: If True, extract only opinions; otherwise world/bank facts

    Returns:
        Tuple of (extracted_facts, chunks_metadata, usage)
@@ -1272,6 +1203,7 @@ async def extract_facts_from_contents(
            context=item.context,
            llm_config=llm_config,
            agent_name=agent_name,
+            extract_opinions=extract_opinions,
        )
        fact_extraction_tasks.append(task)

@@ -1376,26 +1308,31 @@ def _convert_causal_relations(relations_from_llm, fact_start_idx: int) -> list[C

 def _add_temporal_offsets(facts: list[ExtractedFactType], contents: list[RetainContent]) -> None:
    """
-    Add time offsets to preserve fact ordering across all contents.
+    Add time offsets to preserve fact ordering within each content.

-    This allows retrieval to distinguish between facts from different documents/conversations
-    even when they have the same base event_date, and also between facts within the same
-    conversation.
-
-    Uses absolute position across all facts to ensure unique timestamps.
+    This allows retrieval to distinguish between facts that happened earlier vs later
+    in the same conversation, even when the base event_date is the same.

    Modifies facts in place.
    """
-    from .orchestrator import parse_datetime_flexible
+    # Group facts by content_index
+    current_content_idx = 0
+    content_fact_start = 0

    for i, fact in enumerate(facts):
-        # Use absolute position across all facts to ensure uniqueness across different contents
-        offset = timedelta(seconds=i * SECONDS_PER_FACT)
+        if fact.content_index != current_content_idx:
+            # Moved to next content
+            current_content_idx = fact.content_index
+            content_fact_start = i

-        # Apply offset to all temporal fields (handle both datetime objects and ISO strings)
+        # Calculate position within this content
+        fact_position = i - content_fact_start
+        offset = timedelta(seconds=fact_position * SECONDS_PER_FACT)
+
+        # Apply offset to all temporal fields
        if fact.occurred_start:
-            fact.occurred_start = parse_datetime_flexible(fact.occurred_start) + offset
+            fact.occurred_start = fact.occurred_start + offset
        if fact.occurred_end:
-            fact.occurred_end = parse_datetime_flexible(fact.occurred_end) + offset
+            fact.occurred_end = fact.occurred_end + offset
        if fact.mentioned_at:
-            fact.mentioned_at = parse_datetime_flexible(fact.mentioned_at) + offset
+            fact.mentioned_at = fact.mentioned_at + offset
@@ -8,7 +8,6 @@ import json
 import logging

 from ..memory_engine import fq_table
-from .fact_extraction import _sanitize_text
 from .types import ProcessedFact

 logger = logging.getLogger(__name__)
@@ -48,7 +47,7 @@ async def insert_facts_batch(
    tags_list = []

    for fact in facts:
-        fact_texts.append(_sanitize_text(fact.fact_text))
+        fact_texts.append(fact.fact_text)
        # Convert embedding to string for asyncpg vector type
        embeddings.append(str(fact.embedding))
        # event_date: Use occurred_start if available, otherwise use mentioned_at
@@ -57,7 +56,7 @@ async def insert_facts_batch(
        occurred_starts.append(fact.occurred_start)
        occurred_ends.append(fact.occurred_end)
        mentioned_ats.append(fact.mentioned_at)
-        contexts.append(_sanitize_text(fact.context))
+        contexts.append(fact.context)
        fact_types.append(fact.fact_type)
        # confidence_score is only for opinion facts
        confidence_scores.append(1.0 if fact.fact_type == "opinion" else None)
@@ -158,8 +157,7 @@ async def handle_document_tracking(
    """
    import hashlib

-    # Sanitize and calculate content hash
-    combined_content = _sanitize_text(combined_content) or ""
+    # Calculate content hash
    content_hash = hashlib.sha256(combined_content.encode()).hexdigest()

    # Always delete old document first if it exists (cascades to units and links)
@@ -8,7 +8,6 @@ import logging
 import time
 import uuid
 from datetime import UTC, datetime
-from typing import Any

 from ..db_utils import acquire_with_retry
 from . import bank_utils
@@ -19,39 +18,6 @@ def utcnow():
    return datetime.now(UTC)


-def parse_datetime_flexible(value: Any) -> datetime:
-    """
-    Parse a datetime value that could be either a datetime object or an ISO string.
-
-    This handles datetime values from both direct Python calls and deserialized JSON
-    (where datetime objects are serialized as ISO strings).
-
-    Args:
-        value: Either a datetime object or an ISO format string
-
-    Returns:
-        datetime object (timezone-aware)
-
-    Raises:
-        TypeError: If value is neither datetime nor string
-        ValueError: If string is not a valid ISO datetime
-    """
-    if isinstance(value, datetime):
-        # Ensure timezone-aware
-        if value.tzinfo is None:
-            return value.replace(tzinfo=UTC)
-        return value
-    elif isinstance(value, str):
-        # Parse ISO format string (handles both 'Z' and '+00:00' timezone formats)
-        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
-        # Ensure timezone-aware
-        if dt.tzinfo is None:
-            return dt.replace(tzinfo=UTC)
-        return dt
-    else:
-        raise TypeError(f"Expected datetime or string, got {type(value).__name__}")
-
-
 from ..response_models import TokenUsage
 from . import (
    chunk_storage,
@@ -123,18 +89,10 @@ async def retain_batch(
        # Merge item-level tags with document-level tags
        item_tags = item.get("tags", []) or []
        merged_tags = list(set(item_tags + (document_tags or [])))
-
-        # 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()
-
        content = RetainContent(
            content=item["content"],
            context=item.get("context", ""),
-            event_date=event_date_value,
+            event_date=item.get("event_date") or utcnow(),
            metadata=item.get("metadata", {}),
            entities=item.get("entities", []),
            tags=merged_tags,
@@ -143,8 +101,11 @@ async def retain_batch(

    # Step 1: Extract facts from all contents
    step_start = time.time()
+    extract_opinions = fact_type_override == "opinion"

-    extracted_facts, chunks, usage = await fact_extraction.extract_facts_from_contents(contents, llm_config, agent_name)
+    extracted_facts, chunks, usage = await fact_extraction.extract_facts_from_contents(
+        contents, llm_config, agent_name, extract_opinions
+    )
    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"
    )
@@ -158,13 +119,6 @@ async def retain_batch(
                # Handle document tracking even with no facts
                if document_id:
                    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 [])
-                    for item in contents_dicts:
-                        item_tags = item.get("tags", []) or []
-                        all_tags.update(item_tags)
-                    merged_tags = list(all_tags)
-
                    retain_params = {}
                    if contents_dicts:
                        first_item = contents_dicts[0]
@@ -179,7 +133,7 @@ async def retain_batch(
                        if first_item.get("metadata"):
                            retain_params["metadata"] = first_item["metadata"]
                    await fact_storage.handle_document_tracking(
-                        conn, bank_id, document_id, combined_content, is_first_batch, retain_params, merged_tags
+                        conn, bank_id, document_id, combined_content, is_first_batch, retain_params, document_tags
                    )
                else:
                    # Check for per-item document_ids
@@ -193,13 +147,6 @@ async def retain_batch(

                    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)
-
                        retain_params = {}
                        if doc_contents:
                            first_item = doc_contents[0][1]
@@ -214,7 +161,7 @@ async def retain_batch(
                            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
+                            conn, bank_id, doc_id, combined_content, is_first_batch, retain_params, document_tags
                        )

        total_time = time.time() - start_time
@@ -266,13 +213,6 @@ async def retain_batch(
                # Legacy: single document_id parameter
                combined_content = "\n".join([c.get("content", "") for c in contents_dicts])
                retain_params = {}
-                # Collect tags from all content items and merge with document_tags
-                all_tags = set(document_tags or [])
-                for item in contents_dicts:
-                    item_tags = item.get("tags", []) or []
-                    all_tags.update(item_tags)
-                merged_tags = list(all_tags)
-
                if contents_dicts:
                    first_item = contents_dicts[0]
                    if first_item.get("context"):
@@ -287,7 +227,7 @@ async def retain_batch(
                        retain_params["metadata"] = first_item["metadata"]

                await fact_storage.handle_document_tracking(
-                    conn, bank_id, document_id, combined_content, is_first_batch, retain_params, merged_tags
+                    conn, bank_id, document_id, combined_content, is_first_batch, retain_params, document_tags
                )
                document_ids_added.append(document_id)
                doc_id_mapping[None] = document_id  # For backwards compatibility
@@ -315,13 +255,6 @@ async def retain_batch(
                            # Combine content for this document
                            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)
-
                            # Extract retain params from first content item
                            retain_params = {}
                            if doc_contents:
@@ -344,7 +277,7 @@ async def retain_batch(
                                combined_content,
                                is_first_batch,
                                retain_params,
-                                merged_tags,
+                                document_tags,
                            )
                            document_ids_added.append(actual_doc_id)

@@ -155,6 +155,7 @@ class LinkExpansionRetriever(GraphRetriever):
                all_seeds.extend(temporal_seeds)

            if not all_seeds:
+                logger.debug("[LinkExpansion] No seeds found, returning empty results")
                return [], timings

            seed_ids = list({s.id for s in all_seeds})
@@ -163,102 +164,30 @@ class LinkExpansionRetriever(GraphRetriever):
            # 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":
-                # 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:
-                # 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,
-                )
+            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"""
@@ -282,69 +211,11 @@ class LinkExpansionRetriever(GraphRetriever):
                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 = 3
-            timings.edge_count = len(entity_rows) + len(causal_rows) + len(fallback_rows)
+            timings.db_queries = 2
+            timings.edge_count = len(entity_rows) + len(causal_rows)

        # 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] = {}

@@ -359,12 +230,6 @@ class LinkExpansionRetriever(GraphRetriever):
            if fact_id not in row_map:
                row_map[fact_id] = dict(row)

-        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]
@@ -0,0 +1,134 @@
+"""
+Scoring functions for memory search and retrieval.
+
+Includes recency weighting, frequency weighting, temporal proximity,
+and similarity calculations used in memory activation and ranking.
+"""
+
+from datetime import datetime
+
+
+def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
+    """
+    Calculate cosine similarity between two vectors.
+
+    Args:
+        vec1: First vector
+        vec2: Second vector
+
+    Returns:
+        Similarity score between 0 and 1
+    """
+    if len(vec1) != len(vec2):
+        raise ValueError("Vectors must have same dimension")
+
+    dot_product = sum(a * b for a, b in zip(vec1, vec2))
+    magnitude1 = sum(a * a for a in vec1) ** 0.5
+    magnitude2 = sum(b * b for b in vec2) ** 0.5
+
+    if magnitude1 == 0 or magnitude2 == 0:
+        return 0.0
+
+    return dot_product / (magnitude1 * magnitude2)
+
+
+def calculate_recency_weight(days_since: float, half_life_days: float = 365.0) -> float:
+    """
+    Calculate recency weight using logarithmic decay.
+
+    This provides much better differentiation over long time periods compared to
+    exponential decay. Uses a log-based decay where the half-life parameter controls
+    when memories reach 50% weight.
+
+    Examples:
+        - Today (0 days): 1.0
+        - 1 year (365 days): ~0.5 (with default half_life=365)
+        - 2 years (730 days): ~0.33
+        - 5 years (1825 days): ~0.17
+        - 10 years (3650 days): ~0.09
+
+    This ensures that 2-year-old and 5-year-old memories have meaningfully
+    different weights, unlike exponential decay which makes them both ~0.
+
+    Args:
+        days_since: Number of days since the memory was created
+        half_life_days: Number of days for weight to reach 0.5 (default: 1 year)
+
+    Returns:
+        Weight between 0 and 1
+    """
+    import math
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_since/half_life))
+    # This decays much slower than exponential, giving better long-term differentiation
+    normalized_age = days_since / half_life_days
+    return 1.0 / (1.0 + math.log1p(normalized_age))
+
+
+def calculate_temporal_anchor(occurred_start: datetime, occurred_end: datetime) -> datetime:
+    """
+    Calculate a single temporal anchor point from a temporal range.
+
+    Used for spreading activation - we need a single representative date
+    to calculate temporal proximity between facts. This simplifies the
+    range-to-range distance problem.
+
+    Strategy: Use midpoint of the range for balanced representation.
+
+    Args:
+        occurred_start: Start of temporal range
+        occurred_end: End of temporal range
+
+    Returns:
+        Single datetime representing the temporal anchor (midpoint)
+
+    Examples:
+        - Point event (July 14): start=July 14, end=July 14 → anchor=July 14
+        - Month range (February): start=Feb 1, end=Feb 28 → anchor=Feb 14
+        - Year range (2023): start=Jan 1, end=Dec 31 → anchor=July 1
+    """
+    # Calculate midpoint
+    time_delta = occurred_end - occurred_start
+    midpoint = occurred_start + (time_delta / 2)
+    return midpoint
+
+
+def calculate_temporal_proximity(anchor_a: datetime, anchor_b: datetime, half_life_days: float = 30.0) -> float:
+    """
+    Calculate temporal proximity between two temporal anchors.
+
+    Used for spreading activation to determine how "close" two facts are
+    in time. Uses logarithmic decay so that temporal similarity doesn't
+    drop off too quickly.
+
+    Args:
+        anchor_a: Temporal anchor of first fact
+        anchor_b: Temporal anchor of second fact
+        half_life_days: Number of days for proximity to reach 0.5
+                       (default: 30 days = 1 month)
+
+    Returns:
+        Proximity score in [0, 1] where:
+        - 1.0 = same day
+        - 0.5 = ~half_life days apart
+        - 0.0 = very distant in time
+
+    Examples:
+        - Same day: 1.0
+        - 1 week apart (half_life=30): ~0.7
+        - 1 month apart (half_life=30): ~0.5
+        - 1 year apart (half_life=30): ~0.2
+    """
+    import math
+
+    days_apart = abs((anchor_a - anchor_b).days)
+
+    if days_apart == 0:
+        return 1.0
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_apart/half_life))
+    # Similar to calculate_recency_weight but for proximity between events
+    normalized_distance = days_apart / half_life_days
+    proximity = 1.0 / (1.0 + math.log1p(normalized_distance))
+
+    return proximity
@@ -188,7 +188,7 @@ def get_system_message(disposition: DispositionTraits) -> str:
        " ".join(instructions) if instructions else "Balance your disposition traits when interpreting information."
    )

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


 async def reflect(
@@ -144,21 +144,17 @@ class BrokerTaskBackend(TaskBackend):
        self,
        pool_getter: Callable[[], "asyncpg.Pool"],
        schema: str | None = None,
-        schema_getter: Callable[[], str | None] | None = None,
    ):
        """
        Initialize the broker task backend.

        Args:
            pool_getter: Callable that returns the asyncpg connection pool
-            schema: Database schema for multi-tenant support (optional, static)
-            schema_getter: Callable that returns current schema dynamically (optional).
-                          If set, takes precedence over static schema for submit_task.
+            schema: Database schema for multi-tenant support (optional)
        """
        super().__init__()
        self._pool_getter = pool_getter
        self._schema = schema
-        self._schema_getter = schema_getter

    async def initialize(self):
        """Initialize the backend."""
@@ -182,19 +178,9 @@ class BrokerTaskBackend(TaskBackend):
        operation_id = task_dict.get("operation_id")
        task_type = task_dict.get("type", "unknown")
        bank_id = task_dict.get("bank_id")
+        payload_json = json.dumps(task_dict)

-        # Custom encoder to handle datetime objects
-        from datetime import datetime
-
-        def datetime_encoder(obj):
-            if isinstance(obj, datetime):
-                return obj.isoformat()
-            raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
-
-        payload_json = json.dumps(task_dict, default=datetime_encoder)
-
-        schema = self._schema_getter() if self._schema_getter else self._schema
-        table = fq_table("async_operations", schema)
+        table = fq_table("async_operations", self._schema)

        if operation_id:
            # Update existing operation with task payload
@@ -245,8 +231,7 @@ class BrokerTaskBackend(TaskBackend):
        import asyncio

        pool = self._pool_getter()
-        schema = self._schema_getter() if self._schema_getter else self._schema
-        table = fq_table("async_operations", schema)
+        table = fq_table("async_operations", self._schema)

        start_time = asyncio.get_event_loop().time()
        while asyncio.get_event_loop().time() - start_time < timeout:
@@ -19,6 +19,7 @@ async def extract_facts(
    context: str = "",
    llm_config: "LLMConfig" = None,
    agent_name: str = None,
+    extract_opinions: bool = False,
 ) -> tuple[list["Fact"], list[tuple[str, int]]]:
    """
    Extract semantic facts from text using LLM.
@@ -35,6 +36,7 @@ async def extract_facts(
        context: Context about the conversation/document
        llm_config: LLM configuration to use
        agent_name: Optional agent name to help identify agent-related facts
+        extract_opinions: If True, extract ONLY opinions. If False, extract world and agent facts (no opinions)

    Returns:
        Tuple of (facts, chunks) where:
@@ -53,6 +55,7 @@ async def extract_facts(
        context=context,
        llm_config=llm_config,
        agent_name=agent_name,
+        extract_opinions=extract_opinions,
    )

    if not facts:
@@ -62,3 +65,129 @@ async def extract_facts(
        return [], chunks

    return facts, chunks
+
+
+def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
+    """
+    Calculate cosine similarity between two vectors.
+
+    Args:
+        vec1: First vector
+        vec2: Second vector
+
+    Returns:
+        Similarity score between 0 and 1
+    """
+    if len(vec1) != len(vec2):
+        raise ValueError("Vectors must have same dimension")
+
+    dot_product = sum(a * b for a, b in zip(vec1, vec2))
+    magnitude1 = sum(a * a for a in vec1) ** 0.5
+    magnitude2 = sum(b * b for b in vec2) ** 0.5
+
+    if magnitude1 == 0 or magnitude2 == 0:
+        return 0.0
+
+    return dot_product / (magnitude1 * magnitude2)
+
+
+def calculate_recency_weight(days_since: float, half_life_days: float = 365.0) -> float:
+    """
+    Calculate recency weight using logarithmic decay.
+
+    This provides much better differentiation over long time periods compared to
+    exponential decay. Uses a log-based decay where the half-life parameter controls
+    when memories reach 50% weight.
+
+    Examples:
+        - Today (0 days): 1.0
+        - 1 year (365 days): ~0.5 (with default half_life=365)
+        - 2 years (730 days): ~0.33
+        - 5 years (1825 days): ~0.17
+        - 10 years (3650 days): ~0.09
+
+    This ensures that 2-year-old and 5-year-old memories have meaningfully
+    different weights, unlike exponential decay which makes them both ~0.
+
+    Args:
+        days_since: Number of days since the memory was created
+        half_life_days: Number of days for weight to reach 0.5 (default: 1 year)
+
+    Returns:
+        Weight between 0 and 1
+    """
+    import math
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_since/half_life))
+    # This decays much slower than exponential, giving better long-term differentiation
+    normalized_age = days_since / half_life_days
+    return 1.0 / (1.0 + math.log1p(normalized_age))
+
+
+def calculate_temporal_anchor(occurred_start: datetime, occurred_end: datetime) -> datetime:
+    """
+    Calculate a single temporal anchor point from a temporal range.
+
+    Used for spreading activation - we need a single representative date
+    to calculate temporal proximity between facts. This simplifies the
+    range-to-range distance problem.
+
+    Strategy: Use midpoint of the range for balanced representation.
+
+    Args:
+        occurred_start: Start of temporal range
+        occurred_end: End of temporal range
+
+    Returns:
+        Single datetime representing the temporal anchor (midpoint)
+
+    Examples:
+        - Point event (July 14): start=July 14, end=July 14 → anchor=July 14
+        - Month range (February): start=Feb 1, end=Feb 28 → anchor=Feb 14
+        - Year range (2023): start=Jan 1, end=Dec 31 → anchor=July 1
+    """
+    # Calculate midpoint
+    time_delta = occurred_end - occurred_start
+    midpoint = occurred_start + (time_delta / 2)
+    return midpoint
+
+
+def calculate_temporal_proximity(anchor_a: datetime, anchor_b: datetime, half_life_days: float = 30.0) -> float:
+    """
+    Calculate temporal proximity between two temporal anchors.
+
+    Used for spreading activation to determine how "close" two facts are
+    in time. Uses logarithmic decay so that temporal similarity doesn't
+    drop off too quickly.
+
+    Args:
+        anchor_a: Temporal anchor of first fact
+        anchor_b: Temporal anchor of second fact
+        half_life_days: Number of days for proximity to reach 0.5
+                       (default: 30 days = 1 month)
+
+    Returns:
+        Proximity score in [0, 1] where:
+        - 1.0 = same day
+        - 0.5 = ~half_life days apart
+        - 0.0 = very distant in time
+
+    Examples:
+        - Same day: 1.0
+        - 1 week apart (half_life=30): ~0.7
+        - 1 month apart (half_life=30): ~0.5
+        - 1 year apart (half_life=30): ~0.2
+    """
+    import math
+
+    days_apart = abs((anchor_a - anchor_b).days)
+
+    if days_apart == 0:
+        return 1.0
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_apart/half_life))
+    # Similar to calculate_recency_weight but for proximity between events
+    normalized_distance = days_apart / half_life_days
+    proximity = 1.0 / (1.0 + math.log1p(normalized_distance))
+
+    return proximity
@@ -16,20 +16,14 @@ with the system (e.g., running migrations for tenant schemas).
 """

 from hindsight_api.extensions.base import Extension
-from hindsight_api.extensions.builtin import ApiKeyTenantExtension, SupabaseTenantExtension
+from hindsight_api.extensions.builtin import ApiKeyTenantExtension
 from hindsight_api.extensions.context import DefaultExtensionContext, ExtensionContext
 from hindsight_api.extensions.http import HttpExtension
 from hindsight_api.extensions.loader import load_extension
-from hindsight_api.extensions.mcp import MCPExtension
 from hindsight_api.extensions.operation_validator import (
    # Consolidation operation
    ConsolidateContext,
    ConsolidateResult,
-    # Mental Model operations
-    MentalModelGetContext,
-    MentalModelGetResult,
-    MentalModelRefreshContext,
-    MentalModelRefreshResult,
    # Core operations
    OperationValidationError,
    OperationValidatorExtension,
@@ -58,8 +52,6 @@ __all__ = [
    "DefaultExtensionContext",
    # HTTP Extension
    "HttpExtension",
-    # MCP Extension
-    "MCPExtension",
    # Operation Validator - Core
    "OperationValidationError",
    "OperationValidatorExtension",
@@ -73,14 +65,8 @@ __all__ = [
    # Operation Validator - Consolidation
    "ConsolidateContext",
    "ConsolidateResult",
-    # Operation Validator - Mental Model
-    "MentalModelGetContext",
-    "MentalModelGetResult",
-    "MentalModelRefreshContext",
-    "MentalModelRefreshResult",
    # Tenant/Auth
    "ApiKeyTenantExtension",
-    "SupabaseTenantExtension",
    "AuthenticationError",
    "RequestContext",
    "Tenant",
@@ -6,17 +6,13 @@ They can be used directly or serve as examples for custom implementations.

 Available built-in extensions:
    - ApiKeyTenantExtension: Simple API key validation with public schema
-    - SupabaseTenantExtension: Supabase JWT validation with per-user schema isolation

 Example usage:
    HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
-    HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.supabase_tenant:SupabaseTenantExtension
 """

-from hindsight_api.extensions.builtin.supabase_tenant import SupabaseTenantExtension
 from hindsight_api.extensions.builtin.tenant import ApiKeyTenantExtension

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

-from hindsight_api.config import get_config
 from hindsight_api.extensions.tenant import AuthenticationError, Tenant, TenantContext, TenantExtension
 from hindsight_api.models import RequestContext


-class DefaultTenantExtension(TenantExtension):
-    """
-    Default single-tenant extension with no authentication.
-
-    This is the default extension used when no tenant extension is configured.
-    It provides single-tenant behavior using the configured schema from
-    HINDSIGHT_API_DATABASE_SCHEMA (defaults to 'public').
-
-    Features:
-    - No authentication required (passes all requests)
-    - Uses configured schema from environment
-    - Perfect for single-tenant deployments without auth
-
-    Configuration:
-        HINDSIGHT_API_DATABASE_SCHEMA=your-schema (optional, defaults to 'public')
-
-    This is automatically enabled by default. To use custom authentication,
-    configure a different tenant extension:
-        HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
-    """
-
-    def __init__(self, config: dict[str, str]):
-        super().__init__(config)
-        # Cache the schema at initialization for consistency
-        # Support explicit schema override via config, otherwise use environment
-        self._schema = config.get("schema", get_config().database_schema)
-
-    async def authenticate(self, context: RequestContext) -> TenantContext:
-        """Return configured schema without any authentication."""
-        return TenantContext(schema_name=self._schema)
-
-    async def list_tenants(self) -> list[Tenant]:
-        """Return configured schema for single-tenant setup."""
-        return [Tenant(schema=self._schema)]
-
-
 class ApiKeyTenantExtension(TenantExtension):
    """
    Built-in tenant extension that validates API key against an environment variable.

    This is a simple implementation that:
    1. Validates the API key matches HINDSIGHT_API_TENANT_API_KEY
-    2. Returns the configured schema (HINDSIGHT_API_DATABASE_SCHEMA, default 'public')
-       for all authenticated requests
+    2. Returns 'public' as the schema for all authenticated requests

    Configuration:
        HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
        HINDSIGHT_API_TENANT_API_KEY=your-secret-key
-        HINDSIGHT_API_DATABASE_SCHEMA=your-schema (optional, defaults to 'public')
-        HINDSIGHT_API_TENANT_MCP_AUTH_DISABLED=true (optional, disable auth for MCP endpoints)

    For multi-tenant setups with separate schemas per tenant, implement a custom
    TenantExtension that looks up the schema based on the API key or token claims.
@@ -65,26 +25,13 @@ class ApiKeyTenantExtension(TenantExtension):
        self.expected_api_key = config.get("api_key")
        if not self.expected_api_key:
            raise ValueError("HINDSIGHT_API_TENANT_API_KEY is required when using ApiKeyTenantExtension")
-        # Allow disabling MCP auth for backwards compatibility
-        self.mcp_auth_disabled = config.get("mcp_auth_disabled", "").lower() in ("true", "1", "yes")

    async def authenticate(self, context: RequestContext) -> TenantContext:
-        """Validate API key and return configured schema context."""
+        """Validate API key and return public schema context."""
        if context.api_key != self.expected_api_key:
            raise AuthenticationError("Invalid API key")
-        return TenantContext(schema_name=get_config().database_schema)
+        return TenantContext(schema_name="public")

    async def list_tenants(self) -> list[Tenant]:
-        """Return configured schema for single-tenant setup."""
-        return [Tenant(schema=get_config().database_schema)]
-
-    async def authenticate_mcp(self, context: RequestContext) -> TenantContext:
-        """
-        Authenticate MCP requests.
-
-        If mcp_auth_disabled is set, skip authentication for backwards compatibility.
-        Otherwise, delegate to authenticate().
-        """
-        if self.mcp_auth_disabled:
-            return TenantContext(schema_name=get_config().database_schema)
-        return await self.authenticate(context)
+        """Return public schema for single-tenant setup."""
+        return [Tenant(schema="public")]
@@ -1,42 +0,0 @@
-"""MCP Extension for registering additional MCP tools.
-
-This extension allows external packages (like hindsight-cloud) to register
-additional MCP tools on the Hindsight MCP server.
-
-Example:
-    HINDSIGHT_API_MCP_EXTENSION=hindsight_cloud.extensions:CloudMCPExtension
-"""
-
-import logging
-from abc import abstractmethod
-
-from fastmcp import FastMCP
-
-from hindsight_api import MemoryEngine
-from hindsight_api.extensions.base import Extension
-
-logger = logging.getLogger(__name__)
-
-
-class MCPExtension(Extension):
-    """Base class for MCP extensions that register additional tools.
-
-    Subclass this to add MCP tools in extension packages.
-
-    Example:
-        class CloudMCPExtension(MCPExtension):
-            def register_tools(self, mcp: FastMCP, memory: MemoryEngine) -> None:
-                @mcp.tool()
-                async def my_custom_tool(query: str) -> str:
-                    return "result"
-    """
-
-    @abstractmethod
-    def register_tools(self, mcp: FastMCP, memory: MemoryEngine) -> None:
-        """Register additional MCP tools.
-
-        Args:
-            mcp: FastMCP server instance to register tools on
-            memory: MemoryEngine instance for accessing memory operations
-        """
-        pass
@@ -196,57 +196,6 @@ class ConsolidateResult:
    error: str | None = None


-# =============================================================================
-# Mental Model Contexts
-# =============================================================================
-
-
-@dataclass
-class MentalModelGetContext:
-    """Context for a mental model GET operation validation (pre-operation)."""
-
-    bank_id: str
-    mental_model_id: str
-    request_context: "RequestContext"
-
-
-@dataclass
-class MentalModelRefreshContext:
-    """Context for a mental model refresh/create operation validation (pre-operation)."""
-
-    bank_id: str
-    mental_model_id: str | None  # None for create (not yet assigned)
-    request_context: "RequestContext"
-
-
-@dataclass
-class MentalModelGetResult:
-    """Result context for post-mental-model-GET hook."""
-
-    bank_id: str
-    mental_model_id: str
-    request_context: "RequestContext"
-    output_tokens: int  # tokens in the returned content
-    success: bool = True
-    error: str | None = None
-
-
-@dataclass
-class MentalModelRefreshResult:
-    """Result context for post-mental-model-refresh hook."""
-
-    bank_id: str
-    mental_model_id: str
-    request_context: "RequestContext"
-    query_tokens: int  # tokens in source_query
-    output_tokens: int  # tokens in generated content
-    context_tokens: int  # tokens in context (if any)
-    facts_used: int  # facts referenced in based_on
-    mental_models_used: int  # mental models referenced in based_on
-    success: bool = True
-    error: str | None = None
-
-
 class OperationValidatorExtension(Extension, ABC):
    """
    Validates and hooks into retain/recall/reflect/consolidate operations.
@@ -453,81 +402,3 @@ class OperationValidatorExtension(Extension, ABC):
                - error: Error message (if failed)
        """
        pass
-
-    # =========================================================================
-    # Mental Model - Pre-operation validation hook (optional - override to implement)
-    # =========================================================================
-
-    async def validate_mental_model_get(self, ctx: MentalModelGetContext) -> ValidationResult:
-        """
-        Validate a mental model GET operation before execution.
-
-        Override to implement custom validation logic for mental model retrieval.
-
-        Args:
-            ctx: Context containing:
-                - bank_id: Bank identifier
-                - mental_model_id: Mental model identifier
-                - request_context: Request context with auth info
-
-        Returns:
-            ValidationResult indicating whether the operation is allowed.
-        """
-        return ValidationResult.accept()
-
-    async def validate_mental_model_refresh(self, ctx: MentalModelRefreshContext) -> ValidationResult:
-        """
-        Validate a mental model refresh/create operation before execution.
-
-        Override to implement custom validation logic for mental model refresh.
-
-        Args:
-            ctx: Context containing:
-                - bank_id: Bank identifier
-                - mental_model_id: Mental model identifier (None for create)
-                - request_context: Request context with auth info
-
-        Returns:
-            ValidationResult indicating whether the operation is allowed.
-        """
-        return ValidationResult.accept()
-
-    # =========================================================================
-    # Mental Model - Post-operation hooks (optional - override to implement)
-    # =========================================================================
-
-    async def on_mental_model_get_complete(self, result: MentalModelGetResult) -> None:
-        """
-        Called after a mental model GET operation completes (success or failure).
-
-        Override to implement post-operation logic such as tracking or audit logging.
-
-        Args:
-            result: Result context containing:
-                - bank_id: Bank identifier
-                - mental_model_id: Mental model identifier
-                - output_tokens: Token count of the returned content
-                - success: Whether the operation succeeded
-                - error: Error message (if failed)
-        """
-        pass
-
-    async def on_mental_model_refresh_complete(self, result: MentalModelRefreshResult) -> None:
-        """
-        Called after a mental model refresh operation completes (success or failure).
-
-        Override to implement post-operation logic such as tracking or audit logging.
-
-        Args:
-            result: Result context containing:
-                - bank_id: Bank identifier
-                - mental_model_id: Mental model identifier
-                - query_tokens: Tokens in source_query
-                - output_tokens: Tokens in generated content
-                - context_tokens: Tokens in context
-                - facts_used: Number of facts referenced
-                - mental_models_used: Number of mental models referenced
-                - success: Whether the operation succeeded
-                - error: Error message (if failed)
-        """
-        pass
@@ -87,22 +87,3 @@ class TenantExtension(Extension, ABC):
            For single-tenant setups, return [Tenant(schema="public")].
        """
        ...
-
-    async def authenticate_mcp(self, context: RequestContext) -> TenantContext:
-        """
-        Authenticate MCP requests.
-
-        By default, this calls authenticate(). Override this method to provide
-        different authentication behavior for MCP endpoints (e.g., to disable
-        auth for backwards compatibility with existing MCP servers).
-
-        Args:
-            context: The action context containing API key and other auth data.
-
-        Returns:
-            TenantContext with the schema_name for database operations.
-
-        Raises:
-            AuthenticationError: If authentication fails.
-        """
-        return await self.authenticate(context)
@@ -20,13 +20,14 @@ import warnings

 import uvicorn

-from . import MemoryEngine, __version__
+from . import MemoryEngine
 from .api import create_app
 from .banner import print_banner
 from .config import DEFAULT_WORKERS, ENV_WORKERS, HindsightConfig, get_config
 from .daemon import (
    DEFAULT_DAEMON_PORT,
    DEFAULT_IDLE_TIMEOUT,
+    DaemonLock,
    IdleTimeoutMiddleware,
    daemonize,
 )
@@ -135,15 +136,30 @@ def main():

    # Daemon mode handling
    if args.daemon:
-        # Use port from args (may be custom for profiles)
-        if args.port == config.port:  # No custom port specified
-            args.port = DEFAULT_DAEMON_PORT
+        # Use fixed daemon port
+        args.port = DEFAULT_DAEMON_PORT
        args.host = "127.0.0.1"  # Only bind to localhost for security

+        # Check if another daemon is already running
+        daemon_lock = DaemonLock()
+        if not daemon_lock.acquire():
+            print(f"Daemon already running (PID: {daemon_lock.get_pid()})", file=sys.stderr)
+            sys.exit(1)
+
        # Fork into background
-        # No lockfile needed - port binding prevents duplicate daemons
        daemonize()

+        # Re-acquire lock in child process
+        daemon_lock = DaemonLock()
+        if not daemon_lock.acquire():
+            sys.exit(1)
+
+        # Register cleanup to release lock
+        def release_lock():
+            daemon_lock.release()
+
+        atexit.register(release_lock)
+
    # Print banner (not in daemon mode)
    if not args.daemon:
        print()
@@ -154,56 +170,31 @@ def main():
    if args.log_level != config.log_level:
        config = HindsightConfig(
            database_url=config.database_url,
-            database_schema=config.database_schema,
            llm_provider=config.llm_provider,
            llm_api_key=config.llm_api_key,
            llm_model=config.llm_model,
            llm_base_url=config.llm_base_url,
            llm_max_concurrent=config.llm_max_concurrent,
-            llm_max_retries=config.llm_max_retries,
-            llm_initial_backoff=config.llm_initial_backoff,
-            llm_max_backoff=config.llm_max_backoff,
            llm_timeout=config.llm_timeout,
-            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,
            retain_llm_provider=config.retain_llm_provider,
            retain_llm_api_key=config.retain_llm_api_key,
            retain_llm_model=config.retain_llm_model,
            retain_llm_base_url=config.retain_llm_base_url,
-            retain_llm_max_concurrent=config.retain_llm_max_concurrent,
-            retain_llm_max_retries=config.retain_llm_max_retries,
-            retain_llm_initial_backoff=config.retain_llm_initial_backoff,
-            retain_llm_max_backoff=config.retain_llm_max_backoff,
-            retain_llm_timeout=config.retain_llm_timeout,
            reflect_llm_provider=config.reflect_llm_provider,
            reflect_llm_api_key=config.reflect_llm_api_key,
            reflect_llm_model=config.reflect_llm_model,
            reflect_llm_base_url=config.reflect_llm_base_url,
-            reflect_llm_max_concurrent=config.reflect_llm_max_concurrent,
-            reflect_llm_max_retries=config.reflect_llm_max_retries,
-            reflect_llm_initial_backoff=config.reflect_llm_initial_backoff,
-            reflect_llm_max_backoff=config.reflect_llm_max_backoff,
-            reflect_llm_timeout=config.reflect_llm_timeout,
            consolidation_llm_provider=config.consolidation_llm_provider,
            consolidation_llm_api_key=config.consolidation_llm_api_key,
            consolidation_llm_model=config.consolidation_llm_model,
            consolidation_llm_base_url=config.consolidation_llm_base_url,
-            consolidation_llm_max_concurrent=config.consolidation_llm_max_concurrent,
-            consolidation_llm_max_retries=config.consolidation_llm_max_retries,
-            consolidation_llm_initial_backoff=config.consolidation_llm_initial_backoff,
-            consolidation_llm_max_backoff=config.consolidation_llm_max_backoff,
-            consolidation_llm_timeout=config.consolidation_llm_timeout,
            embeddings_provider=config.embeddings_provider,
            embeddings_local_model=config.embeddings_local_model,
-            embeddings_local_force_cpu=config.embeddings_local_force_cpu,
            embeddings_tei_url=config.embeddings_tei_url,
            embeddings_openai_base_url=config.embeddings_openai_base_url,
            embeddings_cohere_base_url=config.embeddings_cohere_base_url,
            reranker_provider=config.reranker_provider,
            reranker_local_model=config.reranker_local_model,
-            reranker_local_force_cpu=config.reranker_local_force_cpu,
-            reranker_local_max_concurrent=config.reranker_local_max_concurrent,
            reranker_tei_url=config.reranker_tei_url,
            reranker_tei_batch_size=config.reranker_tei_batch_size,
            reranker_tei_max_concurrent=config.reranker_tei_max_concurrent,
@@ -218,14 +209,16 @@ def main():
            mpfp_top_k_neighbors=config.mpfp_top_k_neighbors,
            recall_max_concurrent=config.recall_max_concurrent,
            recall_connection_budget=config.recall_connection_budget,
+            observation_min_facts=config.observation_min_facts,
+            observation_top_entities=config.observation_top_entities,
            retain_max_completion_tokens=config.retain_max_completion_tokens,
            retain_chunk_size=config.retain_chunk_size,
            retain_extract_causal_links=config.retain_extract_causal_links,
            retain_extraction_mode=config.retain_extraction_mode,
-            retain_custom_instructions=config.retain_custom_instructions,
-            enable_observations=config.enable_observations,
+            retain_observations_async=config.retain_observations_async,
+            enable_mental_models=config.enable_mental_models,
+            consolidation_similarity_threshold=config.consolidation_similarity_threshold,
            consolidation_batch_size=config.consolidation_batch_size,
-            consolidation_max_tokens=config.consolidation_max_tokens,
            skip_llm_verification=config.skip_llm_verification,
            lazy_reranker=config.lazy_reranker,
            run_migrations_on_startup=config.run_migrations_on_startup,
@@ -237,16 +230,10 @@ def main():
            worker_id=config.worker_id,
            worker_poll_interval_ms=config.worker_poll_interval_ms,
            worker_max_retries=config.worker_max_retries,
+            worker_batch_size=config.worker_batch_size,
            worker_http_port=config.worker_http_port,
-            worker_max_slots=config.worker_max_slots,
-            worker_consolidation_max_slots=config.worker_consolidation_max_slots,
            reflect_max_iterations=config.reflect_max_iterations,
            mental_model_refresh_concurrency=config.mental_model_refresh_concurrency,
-            otel_traces_enabled=config.otel_traces_enabled,
-            otel_exporter_otlp_endpoint=config.otel_exporter_otlp_endpoint,
-            otel_exporter_otlp_headers=config.otel_exporter_otlp_headers,
-            otel_service_name=config.otel_service_name,
-            otel_deployment_environment=config.otel_deployment_environment,
        )
    config.configure_logging()
    if not args.daemon:
@@ -351,13 +338,11 @@ def main():
            embeddings_provider=config.embeddings_provider,
            reranker_provider=config.reranker_provider,
            mcp_enabled=config.mcp_enabled,
-            version=__version__,
        )

    # Start idle checker in daemon mode
    if idle_middleware is not None:
        # Start the idle checker in a background thread with its own event loop
-        import logging
        import threading

        def run_idle_checker():
@@ -368,12 +353,12 @@ def main():
                loop = asyncio.new_event_loop()
                asyncio.set_event_loop(loop)
                loop.run_until_complete(idle_middleware._check_idle())
-            except Exception as e:
-                logging.error(f"Idle checker error: {e}", exc_info=True)
+            except Exception:
+                pass

        threading.Thread(target=run_idle_checker, daemon=True).start()

-    uvicorn.run(**uvicorn_config)
+    uvicorn.run(**uvicorn_config)  # type: ignore[invalid-argument-type] - dict kwargs


 if __name__ == "__main__":
@@ -32,9 +32,6 @@ class MCPToolsConfig:
    # How to resolve bank_id for operations
    bank_id_resolver: Callable[[], str | None]

-    # How to resolve API key for tenant auth (optional)
-    api_key_resolver: Callable[[], str | None] | None = None
-
    # Whether to include bank_id as a parameter on tools (for multi-bank support)
    include_bank_id_param: bool = False

@@ -49,16 +46,6 @@ class MCPToolsConfig:
    retain_fire_and_forget: bool = False  # If True, use asyncio.create_task pattern


-def _get_request_context(config: MCPToolsConfig) -> RequestContext:
-    """Create RequestContext with API key from resolver if available.
-
-    This enables tenant auth to work with MCP tools by propagating
-    the Bearer token from the MCP middleware to the memory engine.
-    """
-    api_key = config.api_key_resolver() if config.api_key_resolver else None
-    return RequestContext(api_key=api_key)
-
-
 def parse_timestamp(timestamp: str) -> datetime | None:
    """Parse an ISO format timestamp string.

@@ -168,14 +155,12 @@ def _register_retain(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig)
                if error:
                    return {"status": "error", "message": error}

-                request_context = _get_request_context(config)
-
                async def _retain():
                    try:
                        await memory.retain_batch_async(
                            bank_id=target_bank,
                            contents=[content_dict],
-                            request_context=request_context,
+                            request_context=RequestContext(),
                        )
                    except Exception as e:
                        logger.error(f"Error storing memory: {e}", exc_info=True)
@@ -211,17 +196,16 @@ def _register_retain(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig)
                        return f"Error: {error}"

                    contents = [content_dict]
-                    request_context = _get_request_context(config)
                    if async_processing:
                        result = await memory.submit_async_retain(
-                            bank_id=target_bank, contents=contents, request_context=request_context
+                            bank_id=target_bank, contents=contents, request_context=RequestContext()
                        )
                        return f"Memory queued for background processing (operation_id: {result.get('operation_id', 'N/A')})"
                    else:
                        await memory.retain_batch_async(
                            bank_id=target_bank,
                            contents=contents,
-                            request_context=request_context,
+                            request_context=RequestContext(),
                        )
                        return f"Memory stored successfully in bank '{target_bank}'"
                except Exception as e:
@@ -253,14 +237,12 @@ def _register_retain(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig)
            if error:
                return {"status": "error", "message": error}

-            request_context = _get_request_context(config)
-
            async def _retain():
                try:
                    await memory.retain_batch_async(
                        bank_id=target_bank,
                        contents=[content_dict],
-                        request_context=request_context,
+                        request_context=RequestContext(),
                    )
                except Exception as e:
                    logger.error(f"Error storing memory: {e}", exc_info=True)
@@ -298,7 +280,7 @@ def _register_recall(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig)
                    fact_type=list(VALID_RECALL_FACT_TYPES),
                    budget=Budget.HIGH,
                    max_tokens=max_tokens,
-                    request_context=_get_request_context(config),
+                    request_context=RequestContext(),
                )

                return recall_result.model_dump_json(indent=2)
@@ -329,7 +311,7 @@ def _register_recall(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig)
                    fact_type=list(VALID_RECALL_FACT_TYPES),
                    budget=Budget.HIGH,
                    max_tokens=max_tokens,
-                    request_context=_get_request_context(config),
+                    request_context=RequestContext(),
                )

                return recall_result.model_dump()
@@ -388,7 +370,7 @@ def _register_reflect(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig
                    query=query,
                    budget=budget_enum,
                    context=context,
-                    request_context=_get_request_context(config),
+                    request_context=RequestContext(),
                )

                return reflect_result.model_dump_json(indent=2)
@@ -441,7 +423,7 @@ def _register_reflect(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig
                    query=query,
                    budget=budget_enum,
                    context=context,
-                    request_context=_get_request_context(config),
+                    request_context=RequestContext(),
                )

                return reflect_result.model_dump()
@@ -465,7 +447,7 @@ def _register_list_banks(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsCon
            JSON list of banks with their IDs, names, dispositions, and missions.
        """
        try:
-            banks = await memory.list_banks(request_context=_get_request_context(config))
+            banks = await memory.list_banks(request_context=RequestContext())
            return json.dumps({"banks": banks}, indent=2)
        except Exception as e:
            logger.error(f"Error listing banks: {e}", exc_info=True)
@@ -489,9 +471,8 @@ def _register_create_bank(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsCo
            mission: Optional mission describing who the agent is and what they're trying to accomplish
        """
        try:
-            request_context = _get_request_context(config)
            # get_bank_profile auto-creates bank if it doesn't exist
-            profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+            profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())

            # Update name/mission if provided
            if name is not None or mission is not None:
@@ -499,10 +480,10 @@ def _register_create_bank(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsCo
                    bank_id,
                    name=name,
                    mission=mission,
-                    request_context=request_context,
+                    request_context=RequestContext(),
                )
                # Fetch updated profile
-                profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+                profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())

            # Serialize disposition if it's a Pydantic model
            if "disposition" in profile and hasattr(profile["disposition"], "model_dump"):
@@ -189,7 +189,7 @@ class MetricsCollectorBase:
        Args:
            provider: LLM provider name (openai, anthropic, gemini, groq, ollama, lmstudio)
            model: Model name
-            scope: Scope identifier (e.g., "memory", "reflect", "consolidation")
+            scope: Scope identifier (e.g., "memory", "reflect", "entity_observation")
            duration: Call duration in seconds
            input_tokens: Number of input/prompt tokens
            output_tokens: Number of output/completion tokens
@@ -321,7 +321,7 @@ class MetricsCollector(MetricsCollectorBase):
                pass

        Args:
-            operation: Operation name (retain, recall, reflect, consolidation)
+            operation: Operation name (retain, recall, reflect, entity_observation)
            bank_id: Memory bank ID
            source: Source of the operation (api, reflect, internal)
            budget: Optional budget level (low, mid, high)
@@ -371,7 +371,7 @@ class MetricsCollector(MetricsCollectorBase):
        Args:
            provider: LLM provider name (openai, anthropic, gemini, groq, ollama, lmstudio)
            model: Model name
-            scope: Scope identifier (e.g., "memory", "reflect", "consolidation")
+            scope: Scope identifier (e.g., "memory", "reflect", "entity_observation")
            duration: Call duration in seconds
            input_tokens: Number of input/prompt tokens
            output_tokens: Number of output/completion tokens
@@ -25,8 +25,6 @@ from alembic.config import Config
 from alembic.script.revision import ResolutionError
 from sqlalchemy import create_engine, text

-from .utils import mask_network_location
-
 logger = logging.getLogger(__name__)

 # Advisory lock ID for migrations (arbitrary unique number)
@@ -56,7 +54,7 @@ def _run_migrations_internal(database_url: str, script_location: str, schema: st
    """
    schema_name = schema or "public"
    logger.info(f"Running database migrations to head for schema '{schema_name}'...")
-    logger.info(f"Database URL: {mask_network_location(database_url)}")
+    logger.info(f"Database URL: {database_url}")
    logger.info(f"Script location: {script_location}")

    # Create Alembic configuration programmatically (no alembic.ini needed)
@@ -167,81 +165,6 @@ def run_migrations(
            logger.debug("Migration advisory lock acquired")

            try:
-                # Ensure pgvector extension is installed globally BEFORE schema migrations
-                # This is critical: the extension must exist database-wide before any schema
-                # migrations run, otherwise custom schemas won't have access to vector types
-                logger.debug("Checking pgvector extension availability...")
-
-                # First, check if extension already exists
-                ext_check = conn.execute(
-                    text(
-                        "SELECT extname, nspname FROM pg_extension e "
-                        "JOIN pg_namespace n ON e.extnamespace = n.oid "
-                        "WHERE extname = 'vector'"
-                    )
-                ).fetchone()
-
-                if ext_check:
-                    # Extension exists - check if in correct schema
-                    ext_schema = ext_check[1]
-                    if ext_schema == "public":
-                        logger.info("pgvector extension found in public schema - ready to use")
-                    else:
-                        # Extension in wrong schema - try to fix if we have permissions
-                        logger.warning(
-                            f"pgvector extension found in schema '{ext_schema}' instead of 'public'. "
-                            f"Attempting to relocate..."
-                        )
-                        try:
-                            conn.execute(text("DROP EXTENSION vector CASCADE"))
-                            conn.execute(text("SET search_path TO public"))
-                            conn.execute(text("CREATE EXTENSION vector"))
-                            conn.commit()
-                            logger.info("pgvector extension relocated to public schema")
-                        except Exception as e:
-                            # Failed to relocate - log but don't fail if extension exists somewhere
-                            logger.warning(
-                                f"Could not relocate pgvector extension to public schema: {e}. "
-                                f"Continuing with extension in '{ext_schema}' schema."
-                            )
-                            conn.rollback()
-                else:
-                    # Extension doesn't exist - try to install
-                    logger.info("pgvector extension not found, attempting to install...")
-                    try:
-                        conn.execute(text("SET search_path TO public"))
-                        conn.execute(text("CREATE EXTENSION vector"))
-                        conn.commit()
-                        logger.info("pgvector extension installed in public schema")
-                    except Exception as e:
-                        # Installation failed - this is only fatal if extension truly doesn't exist
-                        # Check one more time in case another process installed it
-                        conn.rollback()
-                        ext_recheck = conn.execute(
-                            text(
-                                "SELECT nspname FROM pg_extension e "
-                                "JOIN pg_namespace n ON e.extnamespace = n.oid "
-                                "WHERE extname = 'vector'"
-                            )
-                        ).fetchone()
-
-                        if ext_recheck:
-                            logger.warning(
-                                f"Could not install pgvector extension (permission denied?), "
-                                f"but extension exists in '{ext_recheck[0]}' schema. Continuing..."
-                            )
-                        else:
-                            # Extension truly doesn't exist and we can't install it
-                            logger.error(
-                                f"pgvector extension is not installed and cannot be installed: {e}. "
-                                f"Please ensure pgvector is installed by a database administrator. "
-                                f"See: https://github.com/pgvector/pgvector#installation"
-                            )
-                            raise RuntimeError(
-                                "pgvector extension is required but not installed. "
-                                "Please install it with: CREATE EXTENSION vector;"
-                            ) from e
-
                # Run migrations while holding the lock
                _run_migrations_internal(database_url, script_location, schema=schema)
            finally:
@@ -40,7 +40,7 @@ class EmbeddedPostgres:
            # Only set port if explicitly specified
            if self.port is not None:
                kwargs["port"] = self.port
-            self._pg0 = Pg0(**kwargs)
+            self._pg0 = Pg0(**kwargs)  # type: ignore[invalid-argument-type] - dict kwargs
        return self._pg0

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

    print(f"Starting Hindsight Worker: {args.worker_id}")
    print(f"  Poll interval: {args.poll_interval}ms")
+    print(f"  Batch size: {args.batch_size}")
    print(f"  Max retries: {args.max_retries}")
-    print(f"  Max slots: {config.worker_max_slots}")
-    print(f"  Consolidation max slots: {config.worker_consolidation_max_slots}")
    print(f"  HTTP server: {args.http_host}:{args.http_port}")
    print()

@@ -176,19 +181,7 @@ def main():
        nonlocal memory, poller
        import uvicorn

-        from ..extensions import OperationValidatorExtension, TenantExtension, load_extension
-
-        # Load tenant extension BEFORE creating MemoryEngine so it can
-        # set correct schema context during task execution. Without this,
-        # _authenticate_tenant sees no extension and resets schema to "public",
-        # causing worker writes to land in the wrong schema.
-        tenant_extension = load_extension("TENANT", TenantExtension)
-
-        # Load operation validator so workers can record usage metering
-        # for async operations (e.g. refresh_mental_model after consolidation)
-        operation_validator = load_extension("OPERATION_VALIDATOR", OperationValidatorExtension)
-        if operation_validator:
-            logger.info(f"Loaded operation validator: {operation_validator.__class__.__name__}")
+        from ..extensions import TenantExtension, load_extension

        # Initialize MemoryEngine
        # Workers use SyncTaskBackend because they execute tasks directly,
@@ -196,63 +189,43 @@ def main():
        memory = MemoryEngine(
            run_migrations=False,  # Workers don't run migrations
            task_backend=SyncTaskBackend(),
-            tenant_extension=tenant_extension,
-            operation_validator=operation_validator,
        )

        await memory.initialize()

        print(f"Database connected: {config.database_url}")

+        # Load tenant extension for dynamic schema discovery
+        tenant_extension = load_extension("TENANT", TenantExtension)
+
        if tenant_extension:
            print("Tenant extension loaded - schemas will be discovered dynamically on each poll")
        else:
-            print(f"No tenant extension configured, using schema: {config.database_schema}")
+            print("No tenant extension configured, using public schema only")

        # Create a single poller that handles all schemas dynamically
-        # Convert default schema to None for SQL compatibility (no schema prefix)
-        from hindsight_api.config import DEFAULT_DATABASE_SCHEMA
-
-        schema = None if config.database_schema == DEFAULT_DATABASE_SCHEMA else config.database_schema
        poller = WorkerPoller(
            pool=memory._pool,
            worker_id=args.worker_id,
            executor=memory.execute_task,
            poll_interval_ms=args.poll_interval,
+            batch_size=args.batch_size,
            max_retries=args.max_retries,
-            schema=schema,
            tenant_extension=tenant_extension,
-            max_slots=config.worker_max_slots,
-            consolidation_max_slots=config.worker_consolidation_max_slots,
        )

        # Create the HTTP app for metrics/health
        app = create_worker_app(poller, memory)

-        # Setup signal handlers for graceful shutdown using asyncio
+        # Setup signal handlers for graceful shutdown
        shutdown_requested = asyncio.Event()
-        force_exit = False

-        loop = asyncio.get_event_loop()
+        def signal_handler(signum, frame):
+            print(f"\nReceived signal {signum}, initiating graceful shutdown...")
+            shutdown_requested.set()

-        def signal_handler():
-            nonlocal force_exit
-            if shutdown_requested.is_set():
-                # Second signal = force exit
-                print("\nReceived second signal, forcing immediate exit...")
-                force_exit = True
-                # Restore default handler so third signal kills process
-                loop.remove_signal_handler(signal.SIGINT)
-                loop.remove_signal_handler(signal.SIGTERM)
-                sys.exit(1)
-            else:
-                print("\nReceived shutdown signal, initiating graceful shutdown...")
-                print("(Press Ctrl+C again to force immediate exit)")
-                shutdown_requested.set()
-
-        # Use asyncio's signal handlers which work properly with the event loop
-        loop.add_signal_handler(signal.SIGINT, signal_handler)
-        loop.add_signal_handler(signal.SIGTERM, signal_handler)
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)

        # Create uvicorn config and server
        uvicorn_config = uvicorn.Config(
@@ -271,10 +244,7 @@ def main():
        print(f"Worker started. Metrics available at http://{args.http_host}:{args.http_port}/metrics")

        # Wait for shutdown signal
-        try:
-            await shutdown_requested.wait()
-        except KeyboardInterrupt:
-            print("\nReceived interrupt, initiating graceful shutdown...")
+        await shutdown_requested.wait()

        # Graceful shutdown
        print("Shutting down HTTP server...")
@@ -57,11 +57,10 @@ class WorkerPoller:
        worker_id: str,
        executor: Callable[[dict[str, Any]], Awaitable[None]],
        poll_interval_ms: int = 500,
+        batch_size: int = 10,
        max_retries: int = 3,
        schema: str | None = None,
        tenant_extension: "TenantExtension | None" = None,
-        max_slots: int = 10,
-        consolidation_max_slots: int = 2,
    ):
        """
        Initialize the worker poller.
@@ -71,158 +70,91 @@ class WorkerPoller:
            worker_id: Unique identifier for this worker
            executor: Async function to execute tasks (typically MemoryEngine.execute_task)
            poll_interval_ms: Interval between polls when no tasks found (milliseconds)
+            batch_size: Maximum number of tasks to claim per poll cycle
            max_retries: Maximum retry attempts before marking task as failed
-            schema: Database schema for single-tenant support (deprecated, use tenant_extension)
-            tenant_extension: Extension for dynamic multi-tenant discovery. If None, creates a
-                            DefaultTenantExtension with the configured schema.
-            max_slots: Maximum concurrent tasks per worker
-            consolidation_max_slots: Maximum concurrent consolidation tasks per worker
+            schema: Database schema for single-tenant support (ignored if tenant_extension is set)
+            tenant_extension: Extension for dynamic multi-tenant discovery. If set, list_tenants()
+                            is called on each poll cycle to discover schemas dynamically.
        """
        self._pool = pool
        self._worker_id = worker_id
        self._executor = executor
        self._poll_interval_ms = poll_interval_ms
+        self._batch_size = batch_size
        self._max_retries = max_retries
        self._schema = schema
-        # Always set tenant extension (use DefaultTenantExtension if none provided)
-        if tenant_extension is None:
-            from ..extensions.builtin.tenant import DefaultTenantExtension
-
-            # Pass schema parameter to DefaultTenantExtension if explicitly provided
-            config = {"schema": schema} if schema else {}
-            tenant_extension = DefaultTenantExtension(config=config)
        self._tenant_extension = tenant_extension
-        self._max_slots = max_slots
-        self._consolidation_max_slots = consolidation_max_slots
        self._shutdown = asyncio.Event()
        self._current_tasks: set[asyncio.Task] = set()
        self._in_flight_count = 0
        self._in_flight_lock = asyncio.Lock()
        self._last_progress_log = 0.0
        self._tasks_completed_since_log = 0
-        # Track active tasks locally: operation_id -> (op_type, bank_id, schema, asyncio.Task)
-        self._active_tasks: dict[str, tuple[str, str, str | None, asyncio.Task]] = {}
-        # Track in-flight tasks by operation type
-        self._in_flight_by_type: dict[str, int] = {}
+        # Track active tasks locally: operation_id -> (op_type, bank_id, schema)
+        self._active_tasks: dict[str, tuple[str, str, str | None]] = {}

    async def _get_schemas(self) -> list[str | None]:
-        """Get list of schemas to poll. Returns [None] for default schema (no prefix)."""
-        from ..config import DEFAULT_DATABASE_SCHEMA
-
-        tenants = await self._tenant_extension.list_tenants()
-        # Convert default schema to None for SQL compatibility (no prefix), keep others as-is
-        return [t.schema if t.schema != DEFAULT_DATABASE_SCHEMA else None for t in tenants]
-
-    async def _get_available_slots(self) -> tuple[int, int]:
-        """
-        Calculate available slots for claiming tasks.
-
-        Returns:
-            (total_available, consolidation_available) tuple
-        """
-        async with self._in_flight_lock:
-            total_in_flight = self._in_flight_count
-            consolidation_in_flight = self._in_flight_by_type.get("consolidation", 0)
-
-        total_available = max(0, self._max_slots - total_in_flight)
-        consolidation_available = max(0, self._consolidation_max_slots - consolidation_in_flight)
-
-        return total_available, consolidation_available
-
-    async def wait_for_active_tasks(self, timeout: float = 10.0) -> bool:
-        """
-        Wait for all active background tasks to complete (test helper).
-
-        This is a test-only utility that allows tests to synchronize with
-        fire-and-forget background tasks without using sleep().
-
-        Args:
-            timeout: Maximum time to wait in seconds
-
-        Returns:
-            True if all tasks completed, False if timeout was reached
-        """
-        start_time = asyncio.get_event_loop().time()
-        while True:
-            async with self._in_flight_lock:
-                if self._in_flight_count == 0:
-                    return True
-
-            elapsed = asyncio.get_event_loop().time() - start_time
-            if elapsed >= timeout:
-                return False
-
-            # Short sleep to avoid busy-waiting
-            await asyncio.sleep(0.01)
+        """Get list of schemas to poll. Returns [None] for public schema."""
+        if self._tenant_extension is not None:
+            tenants = await self._tenant_extension.list_tenants()
+            # Convert "public" to None for SQL compatibility, keep others as-is
+            return [t.schema if t.schema != "public" else None for t in tenants]
+        # Single schema mode
+        return [self._schema]

    async def claim_batch(self) -> list[ClaimedTask]:
        """
-        Claim pending tasks atomically across all tenant schemas,
-        respecting slot limits (total and consolidation).
+        Claim up to batch_size pending tasks atomically across all tenant schemas.

        Uses FOR UPDATE SKIP LOCKED to ensure no conflicts with other workers.

+        For consolidation tasks specifically, skips pending tasks if there's already
+        a processing consolidation for the same bank (to avoid duplicate work).
+
+        If tenant_extension is configured, dynamically discovers schemas on each call.
+
        Returns:
            List of ClaimedTask objects containing operation_id, task_dict, and schema
        """
-        # Calculate available slots
-        total_available, consolidation_available = await self._get_available_slots()
-
-        if total_available <= 0:
-            return []
-
        schemas = await self._get_schemas()
        all_tasks: list[ClaimedTask] = []
-        remaining_total = total_available
-        remaining_consolidation = consolidation_available
+        remaining_batch = self._batch_size

        for schema in schemas:
-            if remaining_total <= 0:
+            if remaining_batch <= 0:
                break

-            tasks = await self._claim_batch_for_schema(schema, remaining_total, remaining_consolidation)
-
-            # Update remaining slots based on what was claimed
-            for task in tasks:
-                op_type = task.task_dict.get("operation_type", "unknown")
-                if op_type == "consolidation":
-                    remaining_consolidation -= 1
-
+            tasks = await self._claim_batch_for_schema(schema, remaining_batch)
            all_tasks.extend(tasks)
-            remaining_total -= len(tasks)
+            remaining_batch -= len(tasks)

        return all_tasks

-    async def _claim_batch_for_schema(
-        self, schema: str | None, limit: int, consolidation_limit: int
-    ) -> list[ClaimedTask]:
-        """Claim tasks from a specific schema respecting slot limits."""
-        try:
-            return await self._claim_batch_for_schema_inner(schema, limit, consolidation_limit)
-        except Exception as e:
-            # Format schema for logging: custom schemas in quotes, None as-is
-            schema_display = f'"{schema}"' if schema else str(schema)
-            logger.warning(f"Worker {self._worker_id} failed to claim tasks for schema {schema_display}: {e}")
-            return []
-
-    async def _claim_batch_for_schema_inner(
-        self, schema: str | None, limit: int, consolidation_limit: int
-    ) -> list[ClaimedTask]:
-        """Inner implementation for claiming tasks from a specific schema with slot limits."""
+    async def _claim_batch_for_schema(self, schema: str | None, limit: int) -> list[ClaimedTask]:
+        """Claim tasks from a specific schema."""
        table = fq_table("async_operations", schema)

        async with self._pool.acquire() as conn:
            async with conn.transaction():
-                # Strategy: Claim non-consolidation tasks first, then consolidation up to limit
-
-                # 1. Claim non-consolidation tasks (up to limit)
-                non_consolidation_rows = await conn.fetch(
+                # Select and lock pending tasks
+                # For consolidation: skip if same bank already has one processing
+                rows = await conn.fetch(
                    f"""
                    SELECT operation_id, task_payload
-                    FROM {table}
-                    WHERE status = 'pending'
-                      AND task_payload IS NOT NULL
-                      AND operation_type != 'consolidation'
+                    FROM {table} AS pending
+                    WHERE status = 'pending' AND task_payload IS NOT NULL
+                    AND (
+                        -- Non-consolidation tasks: always claimable
+                        operation_type != 'consolidation'
+                        OR
+                        -- Consolidation: only if no other consolidation processing for same bank
+                        NOT EXISTS (
+                            SELECT 1 FROM {table} AS processing
+                            WHERE processing.bank_id = pending.bank_id
+                            AND processing.operation_type = 'consolidation'
+                            AND processing.status = 'processing'
+                        )
+                    )
                    ORDER BY created_at
                    LIMIT $1
                    FOR UPDATE SKIP LOCKED
@@ -230,39 +162,11 @@ class WorkerPoller:
                    limit,
                )

-                claimed_count = len(non_consolidation_rows)
-                remaining_limit = limit - claimed_count
-
-                # 2. Claim consolidation tasks (up to consolidation_limit and remaining_limit)
-                consolidation_rows = []
-                if consolidation_limit > 0 and remaining_limit > 0:
-                    consolidation_rows = await conn.fetch(
-                        f"""
-                        SELECT operation_id, task_payload
-                        FROM {table} AS pending
-                        WHERE status = 'pending'
-                          AND task_payload IS NOT NULL
-                          AND operation_type = 'consolidation'
-                          AND NOT EXISTS (
-                              SELECT 1 FROM {table} AS processing
-                              WHERE processing.bank_id = pending.bank_id
-                                AND processing.operation_type = 'consolidation'
-                                AND processing.status = 'processing'
-                          )
-                        ORDER BY created_at
-                        LIMIT $1
-                        FOR UPDATE SKIP LOCKED
-                        """,
-                        min(consolidation_limit, remaining_limit),
-                    )
-
-                all_rows = non_consolidation_rows + consolidation_rows
-
-                if not all_rows:
+                if not rows:
                    return []

                # Claim the tasks by updating status and worker_id
-                operation_ids = [row["operation_id"] for row in all_rows]
+                operation_ids = [row["operation_id"] for row in rows]
                await conn.execute(
                    f"""
                    UPDATE {table}
@@ -280,7 +184,7 @@ class WorkerPoller:
                        task_dict=json.loads(row["task_payload"]),
                        schema=schema,
                    )
-                    for row in all_rows
+                    for row in rows
                ]

    async def _mark_completed(self, operation_id: str, schema: str | None):
@@ -346,45 +250,17 @@ class WorkerPoller:
            logger.warning(f"Task {operation_id} failed, will retry (attempt {retry_count + 1}/{self._max_retries})")

    async def execute_task(self, task: ClaimedTask):
-        """Execute a single task as a background job (fire-and-forget)."""
+        """Execute a single task and update its status."""
        task_type = task.task_dict.get("type", "unknown")
-        operation_type = task.task_dict.get("operation_type", "unknown")
        bank_id = task.task_dict.get("bank_id", "unknown")

-        # Create background task
-        bg_task = asyncio.create_task(self._execute_task_inner(task))
-
        # Track this task as active
        async with self._in_flight_lock:
-            self._active_tasks[task.operation_id] = (task_type, bank_id, task.schema, bg_task)
-            self._in_flight_count += 1
-            self._in_flight_by_type[operation_type] = self._in_flight_by_type.get(operation_type, 0) + 1
-
-        # Add cleanup callback
-        bg_task.add_done_callback(lambda _: asyncio.create_task(self._cleanup_task(task.operation_id, operation_type)))
-
-    async def _cleanup_task(self, operation_id: str, operation_type: str):
-        """Remove task from tracking after completion."""
-        async with self._in_flight_lock:
-            if operation_id in self._active_tasks:
-                self._active_tasks.pop(operation_id, None)
-                self._in_flight_count -= 1
-                count = self._in_flight_by_type.get(operation_type, 0)
-                if count > 0:
-                    self._in_flight_by_type[operation_type] = count - 1
-                    if self._in_flight_by_type[operation_type] == 0:
-                        del self._in_flight_by_type[operation_type]
-
-    async def _execute_task_inner(self, task: ClaimedTask):
-        """Inner task execution with error handling."""
-        task_type = task.task_dict.get("type", "unknown")
-        bank_id = task.task_dict.get("bank_id", "unknown")
+            self._active_tasks[task.operation_id] = (task_type, bank_id, task.schema)

        try:
            schema_info = f", schema={task.schema}" if task.schema else ""
            logger.debug(f"Executing task {task.operation_id} (type={task_type}, bank={bank_id}{schema_info})")
-            if task.schema:
-                task.task_dict["_schema"] = task.schema
            await self._executor(task.task_dict)
            await self._mark_completed(task.operation_id, task.schema)
            logger.debug(f"Task {task.operation_id} completed successfully")
@@ -392,6 +268,10 @@ class WorkerPoller:
            error_msg = f"{type(e).__name__}: {e}\n{traceback.format_exc()}"
            logger.error(f"Task {task.operation_id} failed: {e}")
            await self._retry_or_fail(task.operation_id, error_msg, task.schema)
+        finally:
+            # Remove from active tasks
+            async with self._in_flight_lock:
+                self._active_tasks.pop(task.operation_id, None)

    async def recover_own_tasks(self) -> int:
        """
@@ -410,25 +290,20 @@ class WorkerPoller:
        total_count = 0

        for schema in schemas:
-            try:
-                table = fq_table("async_operations", schema)
+            table = fq_table("async_operations", schema)

-                result = await self._pool.execute(
-                    f"""
-                    UPDATE {table}
-                    SET status = 'pending', worker_id = NULL, claimed_at = NULL, updated_at = now()
-                    WHERE status = 'processing' AND worker_id = $1
-                    """,
-                    self._worker_id,
-                )
+            result = await self._pool.execute(
+                f"""
+                UPDATE {table}
+                SET status = 'pending', worker_id = NULL, claimed_at = NULL, updated_at = now()
+                WHERE status = 'processing' AND worker_id = $1
+                """,
+                self._worker_id,
+            )

-                # Parse "UPDATE N" to get count
-                count = int(result.split()[-1]) if result else 0
-                total_count += count
-            except Exception as e:
-                # Format schema for logging: custom schemas in quotes, None as-is
-                schema_display = f'"{schema}"' if schema else str(schema)
-                logger.warning(f"Worker {self._worker_id} failed to recover tasks for schema {schema_display}: {e}")
+            # Parse "UPDATE N" to get count
+            count = int(result.split()[-1]) if result else 0
+            total_count += count

        if total_count > 0:
            logger.info(f"Worker {self._worker_id} recovered {total_count} stale tasks from previous run")
@@ -436,60 +311,59 @@ class WorkerPoller:

    async def run(self):
        """
-        Main polling loop with fire-and-forget task execution.
+        Main polling loop.

-        Continuously polls for pending tasks, spawns them as background tasks,
-        and immediately continues polling (up to slot limits).
+        Continuously polls for pending tasks, claims them, and executes them
+        until shutdown is signaled.
+
+        If tenant_extension is configured, dynamically discovers schemas on each poll.
        """
+        # Recover any tasks from a previous crash before starting
        await self.recover_own_tasks()

-        logger.info(
-            f"Worker {self._worker_id} starting polling loop "
-            f"(max_slots={self._max_slots}, consolidation_max_slots={self._consolidation_max_slots})"
-        )
+        logger.info(f"Worker {self._worker_id} starting polling loop")

        while not self._shutdown.is_set():
            try:
-                # Claim a batch of tasks (respecting slot limits)
+                # Claim a batch of tasks (across all tenant schemas if configured)
                tasks = await self.claim_batch()

                if tasks:
                    # Log batch info
                    task_types: dict[str, int] = {}
                    schemas_seen: set[str | None] = set()
-                    consolidation_count = 0
                    for task in tasks:
                        t = task.task_dict.get("type", "unknown")
-                        op_type = task.task_dict.get("operation_type", "unknown")
                        task_types[t] = task_types.get(t, 0) + 1
                        schemas_seen.add(task.schema)
-                        if op_type == "consolidation":
-                            consolidation_count += 1
-
                    types_str = ", ".join(f"{k}:{v}" for k, v in task_types.items())
-                    # Display None as "default" in logs
-                    schemas_str = ", ".join(s if s else "default" for s in schemas_seen)
+                    schemas_str = ", ".join(s or "public" for s in schemas_seen)
                    logger.info(
-                        f"Worker {self._worker_id} claimed {len(tasks)} tasks "
-                        f"({consolidation_count} consolidation): {types_str} (schemas: {schemas_str})"
+                        f"Worker {self._worker_id} claimed {len(tasks)} tasks: {types_str} (schemas: {schemas_str})"
                    )

-                    # Spawn tasks as background jobs (fire-and-forget)
-                    for task in tasks:
-                        await self.execute_task(task)
+                    # Track in-flight tasks
+                    async with self._in_flight_lock:
+                        self._in_flight_count += len(tasks)

-                    # Continue immediately to claim more tasks (if slots available)
-                    continue
-
-                # No tasks claimed (either no pending tasks or slots full)
-                # Wait before polling again
-                try:
-                    await asyncio.wait_for(
-                        self._shutdown.wait(),
-                        timeout=self._poll_interval_ms / 1000,
-                    )
-                except asyncio.TimeoutError:
-                    pass  # Normal timeout, continue polling
+                    # Execute tasks concurrently
+                    try:
+                        await asyncio.gather(
+                            *[self.execute_task(task) for task in tasks],
+                            return_exceptions=True,
+                        )
+                    finally:
+                        async with self._in_flight_lock:
+                            self._in_flight_count -= len(tasks)
+                else:
+                    # No tasks found, wait before polling again
+                    try:
+                        await asyncio.wait_for(
+                            self._shutdown.wait(),
+                            timeout=self._poll_interval_ms / 1000,
+                        )
+                    except asyncio.TimeoutError:
+                        pass  # Normal timeout, continue polling

                # Log progress stats periodically
                await self._log_progress_if_due()
@@ -520,27 +394,15 @@ class WorkerPoller:
        while asyncio.get_event_loop().time() - start_time < timeout:
            async with self._in_flight_lock:
                in_flight = self._in_flight_count
-                active_task_objects = [task_info[3] for task_info in self._active_tasks.values()]

            if in_flight == 0:
                logger.info(f"Worker {self._worker_id} graceful shutdown complete")
                return

            logger.info(f"Worker {self._worker_id} waiting for {in_flight} in-flight tasks")
+            await asyncio.sleep(0.5)

-            # Wait for at least one task to complete
-            if active_task_objects:
-                done, _ = await asyncio.wait(active_task_objects, timeout=0.5, return_when=asyncio.FIRST_COMPLETED)
-            else:
-                await asyncio.sleep(0.5)
-
-        logger.warning(f"Worker {self._worker_id} shutdown timeout after {timeout}s, cancelling remaining tasks")
-
-        # Cancel remaining tasks
-        async with self._in_flight_lock:
-            for operation_id, (_, _, _, bg_task) in list(self._active_tasks.items()):
-                if not bg_task.done():
-                    bg_task.cancel()
+        logger.warning(f"Worker {self._worker_id} shutdown timeout after {timeout}s")

    async def _log_progress_if_due(self):
        """Log progress stats every PROGRESS_LOG_INTERVAL seconds."""
@@ -551,19 +413,14 @@ class WorkerPoller:
        self._last_progress_log = now

        try:
-            # Get local active tasks
+            # Get local active tasks (this worker only)
            async with self._in_flight_lock:
                in_flight = self._in_flight_count
-                in_flight_by_type = dict(self._in_flight_by_type)
-                active_tasks = dict(self._active_tasks)
+                active_tasks = dict(self._active_tasks)  # Copy to avoid holding lock

-            consolidation_count = in_flight_by_type.get("consolidation", 0)
-            available_slots = self._max_slots - in_flight
-            available_consolidation_slots = self._consolidation_max_slots - consolidation_count
-
-            # Build local processing breakdown
+            # Build local processing breakdown grouped by (op_type, bank_id)
            task_groups: dict[tuple[str, str], int] = {}
-            for op_type, bank_id, _, _ in active_tasks.values():
+            for op_type, bank_id, _ in active_tasks.values():
                key = (op_type, bank_id)
                task_groups[key] = task_groups.get(key, 0) + 1

@@ -572,7 +429,7 @@ class WorkerPoller:
            if len(processing_info) > 10:
                processing_str += f" +{len(processing_info) - 10} more"

-            # Get global stats from DB
+            # Get global stats from DB across all schemas
            schemas = await self._get_schemas()
            global_pending = 0
            all_worker_counts: dict[str, int] = {}
@@ -584,6 +441,7 @@ class WorkerPoller:
                    row = await conn.fetchrow(f"SELECT COUNT(*) as count FROM {table} WHERE status = 'pending'")
                    global_pending += row["count"] if row else 0

+                    # Get processing breakdown by worker
                    worker_rows = await conn.fetch(
                        f"""
                        SELECT worker_id, COUNT(*) as count
@@ -596,18 +454,16 @@ class WorkerPoller:
                        wid = wr["worker_id"] or "unknown"
                        all_worker_counts[wid] = all_worker_counts.get(wid, 0) + wr["count"]

+            # Format other workers' processing counts
            other_workers = []
            for wid, cnt in all_worker_counts.items():
                if wid != self._worker_id:
                    other_workers.append(f"{wid}:{cnt}")
            others_str = ", ".join(other_workers) if other_workers else "none"

-            # Display None as "default" in logs
-            schemas_str = ", ".join(s if s else "default" for s in schemas)
+            schemas_str = ", ".join(s or "public" for s in schemas)
            logger.info(
-                f"[WORKER_STATS] worker={self._worker_id} "
-                f"slots={in_flight}/{self._max_slots} (consolidation={consolidation_count}/{self._consolidation_max_slots}) | "
-                f"available={available_slots} (consolidation={available_consolidation_slots}) | "
+                f"[WORKER_STATS] worker={self._worker_id} in_flight={in_flight} | "
                f"global: pending={global_pending} (schemas: {schemas_str}) | "
                f"others: {others_str} | "
                f"my_active: {processing_str}"
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-api"
-version = "0.4.10"
+version = "0.3.0"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,36 +25,31 @@ dependencies = [
    "psycopg2-binary>=2.9.11",
    "tiktoken>=0.12.0",
    "httpx>=0.27.0",
-    "PyJWT[crypto]>=2.8.0",
-    "fastmcp>=2.14.0", # CVE-2025-66416
+    "fastmcp>=2.14.0",  # CVE-2025-66416
    "pg0-embedded>=0.11.0",
    "python-dateutil>=2.8.0",
    "opentelemetry-api>=1.20.0",
    "opentelemetry-sdk>=1.20.0",
    "opentelemetry-instrumentation-fastapi>=0.41b0",
    "opentelemetry-exporter-prometheus>=0.41b0",
-    "opentelemetry-exporter-otlp-proto-http>=1.20.0",
-    "opentelemetry-semantic-conventions>=0.41b0",
    "dateparser>=1.2.2",
    "google-genai>=1.0.0",
-    "google-auth>=2.0.0",
    "anthropic>=0.40.0",
    "typer>=0.9.0",
    "cohere>=5.0.0",
    "flashrank>=0.2.0",
    # Local ML models for embeddings/reranking - can be excluded in Docker with INCLUDE_LOCAL_MODELS=false
    "sentence-transformers>=3.3.0",
-    "transformers>=4.53.0", # Security fixes for ReDoS vulnerabilities
-    "torch>=2.6.0", # CVE fix for remote code execution
+    "transformers>=4.53.0",  # Security fixes for ReDoS vulnerabilities
+    "torch>=2.6.0",  # CVE fix for remote code execution
    "uvloop>=0.22.1",
    # Transitive dependency security fixes
-    "pyasn1>=0.6.2", # DoS vulnerability fix
-    "urllib3>=2.6.3", # Decompression-bomb safeguards bypass fix
-    "langchain-core>=1.2.5", # Serialization injection vulnerability fix
-    "filelock>=3.20.1", # TOCTOU race condition fix
-    "authlib>=1.6.6", # Account takeover vulnerability fix
-    "aiohttp>=3.13.3", # Multiple DoS vulnerabilities
-    "claude-agent-sdk>=0.1.27",
+    "pyasn1>=0.6.2",  # DoS vulnerability fix
+    "urllib3>=2.6.3",  # Decompression-bomb safeguards bypass fix
+    "langchain-core>=1.2.5",  # Serialization injection vulnerability fix
+    "filelock>=3.20.1",  # TOCTOU race condition fix
+    "authlib>=1.6.6",  # Account takeover vulnerability fix
+    "aiohttp>=3.13.3",  # Multiple DoS vulnerabilities
 ]

 [project.optional-dependencies]
@@ -146,11 +141,6 @@ known-third-party = ["alembic"]
 quote-style = "double"
 indent-style = "space"

-[tool.uv]
-# Allow uv to search all configured indexes for packages, not just the first one
-# This prevents dependency resolution failures when using pytorch index + PyPI
-index-strategy = "unsafe-best-match"
-
 [tool.ty]
 # Type checking configuration
 # ty is an extremely fast Python type checker from Astral (same team as ruff/uv)
@@ -220,34 +220,3 @@ async def memory(pg0_db_url, embeddings, cross_encoder, query_analyzer):
            await mem.close()
    except Exception:
        pass
-
-
-@pytest_asyncio.fixture(scope="function")
-async def memory_no_llm_verify(pg0_db_url, embeddings, cross_encoder, query_analyzer):
-    """
-    Provide a MemoryEngine instance that skips LLM connection verification.
-
-    This fixture is useful for tests that override the LLM configuration
-    after initialization (e.g., to test specific providers).
-    """
-    mem = MemoryEngine(
-        db_url=pg0_db_url,
-        memory_llm_provider="mock",  # Use mock provider as placeholder
-        memory_llm_api_key="",
-        memory_llm_model="mock",
-        embeddings=embeddings,
-        cross_encoder=cross_encoder,
-        query_analyzer=query_analyzer,
-        pool_min_size=1,
-        pool_max_size=5,
-        run_migrations=False,
-        task_backend=SyncTaskBackend(),
-        skip_llm_verification=True,  # Skip verification - will be overridden by test
-    )
-    await mem.initialize()
-    yield mem
-    try:
-        if mem._pool and not mem._pool._closing:
-            await mem.close()
-    except Exception:
-        pass
@@ -1,109 +0,0 @@
-"""
-Tests for configuration validation.
-
-Verifies that config validation catches invalid parameter combinations.
-"""
-
-import os
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def setup_test_env():
-    """Set up environment for each test, restoring original values after."""
-    from hindsight_api.config import clear_config_cache
-
-    # Save original environment values
-    env_vars_to_save = [
-        "HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS",
-        "HINDSIGHT_API_RETAIN_CHUNK_SIZE",
-        "HINDSIGHT_API_LLM_PROVIDER",
-        "HINDSIGHT_API_LLM_MODEL",
-    ]
-
-    # Save original values
-    original_values = {}
-    for key in env_vars_to_save:
-        original_values[key] = os.environ.get(key)
-
-    clear_config_cache()
-
-    yield
-
-    # Restore original environment
-    for key, original_value in original_values.items():
-        if original_value is None:
-            os.environ.pop(key, None)
-        else:
-            os.environ[key] = original_value
-
-    clear_config_cache()
-
-
-def test_retain_max_completion_tokens_must_be_greater_than_chunk_size():
-    """Test that RETAIN_MAX_COMPLETION_TOKENS > RETAIN_CHUNK_SIZE validation works."""
-    from hindsight_api.config import HindsightConfig
-
-    # Set invalid config: max_completion_tokens <= chunk_size
-    os.environ["HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"] = "1000"
-    os.environ["HINDSIGHT_API_RETAIN_CHUNK_SIZE"] = "2000"
-    os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "mock"
-
-    # Should raise ValueError with helpful message
-    with pytest.raises(ValueError) as exc_info:
-        HindsightConfig.from_env()
-
-    error_message = str(exc_info.value)
-
-    # Verify error message contains helpful information
-    assert "HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS" in error_message
-    assert "1000" in error_message
-    assert "HINDSIGHT_API_RETAIN_CHUNK_SIZE" in error_message
-    assert "2000" in error_message
-    assert "must be greater than" in error_message
-    assert "You have two options to fix this:" in error_message
-    assert "Increase HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS" in error_message
-    assert "Use a model that supports" in error_message
-
-
-def test_retain_max_completion_tokens_equal_to_chunk_size_fails():
-    """Test that RETAIN_MAX_COMPLETION_TOKENS == RETAIN_CHUNK_SIZE also fails."""
-    from hindsight_api.config import HindsightConfig
-
-    # Set invalid config: max_completion_tokens == chunk_size
-    os.environ["HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"] = "3000"
-    os.environ["HINDSIGHT_API_RETAIN_CHUNK_SIZE"] = "3000"
-    os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "mock"
-
-    # Should raise ValueError
-    with pytest.raises(ValueError) as exc_info:
-        HindsightConfig.from_env()
-
-    error_message = str(exc_info.value)
-    assert "must be greater than" in error_message
-
-
-def test_valid_retain_config_succeeds():
-    """Test that valid config with max_completion_tokens > chunk_size works."""
-    from hindsight_api.config import HindsightConfig
-
-    # Set valid config: max_completion_tokens > chunk_size
-    os.environ["HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"] = "64000"
-    os.environ["HINDSIGHT_API_RETAIN_CHUNK_SIZE"] = "3000"
-    os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "mock"
-
-    # Should not raise
-    config = HindsightConfig.from_env()
-    assert config.retain_max_completion_tokens == 64000
-    assert config.retain_chunk_size == 3000
-
-
-# Note: The BadRequestError wrapping is implemented in fact_extraction.py
-# but requires a complex integration test setup. The functionality is
-# straightforward: when a BadRequestError containing keywords like
-# "max_tokens", "max_completion_tokens", or "maximum context" is caught,
-# it's wrapped in a ValueError with helpful guidance.
-#
-# The config validation tests above ensure users get early feedback
-# about invalid configurations before runtime errors occur.
@@ -58,6 +58,7 @@ async def test_fact_extraction_basic_analysis(llm_config):
        llm_config=llm_config,
        agent_name="test-agent",
        context="Friday Standup meeting",
+        extract_opinions=False,
    )

    duration = time.time() - start_time
@@ -1063,169 +1063,3 @@ async def test_retain_async_no_usage(api_client):

    # Usage should be None for async operations
    assert result.get("usage") is None, "Async retain should not include usage"
-
-
-@pytest.mark.asyncio
-async def test_version_endpoint_returns_correct_version(api_client):
-    """Test that the /version endpoint returns the correct API version.
-
-    The version should match the __version__ defined in hindsight_api.__init__.py
-    and should not be a hardcoded string.
-    """
-    from hindsight_api import __version__
-
-    # Call the /version endpoint
-    response = await api_client.get("/version")
-    assert response.status_code == 200
-    result = response.json()
-
-    # Verify response structure
-    assert "api_version" in result, "Response should include 'api_version' field"
-    assert "features" in result, "Response should include 'features' field"
-
-    # Verify the version matches the package version
-    assert result["api_version"] == __version__, (
-        f"API version should be {__version__}, got {result['api_version']}"
-    )
-
-    # Verify features field structure
-    features = result["features"]
-    assert "observations" in features
-    assert "mcp" in features
-    assert "worker" in features
-    assert isinstance(features["observations"], bool)
-    assert isinstance(features["mcp"], bool)
-    assert isinstance(features["worker"], bool)
-
-    print(f"Version endpoint returned: api_version={result['api_version']}, features={features}")
-
-
-@pytest.mark.asyncio
-async def test_retain_with_timestamp_async(api_client, test_bank_id):
-    """Test that async retain accepts timestamp field and serializes correctly."""
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "Test memory with timestamp",
-                    "context": "test",
-                    "timestamp": "2026-01-30T11:45:00Z"
-                }
-            ],
-            "async": True
-        }
-    )
-    
-    assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
-    data = response.json()
-    assert data["success"] is True
-    assert data["async"] is True
-    assert "operation_id" in data
-    
-
-@pytest.mark.asyncio
-async def test_retain_with_timestamp_sync(api_client, test_bank_id):
-    """Test that sync retain accepts timestamp field."""
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "Test memory with timestamp sync",
-                    "context": "test", 
-                    "timestamp": "2026-01-30T11:45:00Z"
-                }
-            ],
-            "async": False
-        }
-    )
-    
-    assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
-    data = response.json()
-    assert data["success"] is True
-    assert data["async"] is False
-    
-
-@pytest.mark.asyncio
-async def test_retain_with_multiple_timestamps(api_client, test_bank_id):
-    """Test that multiple items with different timestamp formats work."""
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "Event 1",
-                    "timestamp": "2026-01-30T11:45:00Z"  # With Z
-                },
-                {
-                    "content": "Event 2", 
-                    "timestamp": "2026-01-30T12:00:00+00:00"  # With timezone
-                },
-                {
-                    "content": "Event 3"  # No timestamp
-                }
-            ],
-            "async": True
-        }
-    )
-    
-    assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
-    data = response.json()
-    assert data["success"] is True
-    assert data["items_count"] == 3
-
-
-@pytest.mark.asyncio
-async def test_retain_with_timestamp_async_complete_processing(api_client, test_bank_id):
-    """Test that async retain with timestamp completes full processing including fact extraction."""
-    # Submit async retain with timestamp
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "The quarterly meeting was held on January 30th 2026",
-                    "context": "meetings",
-                    "timestamp": "2026-01-30T11:45:00Z"
-                }
-            ],
-            "async": True
-        }
-    )
-    
-    assert response.status_code == 200, f"Expected 200, got {response.status_code}: {response.text}"
-    data = response.json()
-    assert data["success"] is True
-    assert data["async"] is True
-    operation_id = data["operation_id"]
-    
-    # Wait for async processing to complete (poll operation status)
-    max_wait_seconds = 30
-    poll_interval = 0.5
-    elapsed = 0
-    operation_completed = False
-    
-    while elapsed < max_wait_seconds:
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/operations/{operation_id}")
-        if response.status_code == 200:
-            op_status = response.json()
-            if op_status.get("status") == "completed":
-                operation_completed = True
-                break
-            elif op_status.get("status") == "failed":
-                raise AssertionError(f"Operation failed: {op_status.get('error_message')}")
-        
-        await asyncio.sleep(poll_interval)
-        elapsed += poll_interval
-    
-    assert operation_completed, f"Async operation did not complete within {max_wait_seconds} seconds"
-    
-    # Verify memories were actually stored
-    response = await api_client.get(
-        f"/v1/default/banks/{test_bank_id}/memories/list",
-        params={"limit": 10}
-    )
-    assert response.status_code == 200
-    items = response.json()["items"]
-    assert len(items) > 0, "Should have stored memories after async processing"
@@ -1,278 +0,0 @@
-"""
-Tests for LinkExpansion graph retrieval.
-
-Tests cover the entity-based graph traversal for observations.
-"""
-
-from datetime import datetime, timezone
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def enable_observations():
-    """Enable observations for all tests in this module."""
-    from hindsight_api.config import get_config
-
-    config = get_config()
-    original_value = config.enable_observations
-    config.enable_observations = True
-    yield
-    config.enable_observations = original_value
-
-
-@pytest.mark.asyncio
-async def test_link_expansion_observation_graph_retrieval(memory, request_context):
-    """
-    Test that observations can find other observations via shared entities.
-
-    This tests the scenario where:
-    1. World fact A has entity "Python"
-    2. World fact B has entity "Python"
-    3. Observation OA is derived from world fact A
-    4. Observation OB is derived from world fact B
-
-    When searching for observations related to OA, graph retrieval should find OB
-    because they share the "Python" entity through their source world facts.
-
-    Current issue: Graph retrieval returns 0 for observations because:
-    - Entity links are copied from world facts to observations during consolidation
-    - But the entity expansion query filters by fact_type
-    - Observations only share entities with world facts (cross-type), not with other observations
-    - So filtering to fact_type='observation' returns 0 results
-    """
-    bank_id = f"test_link_expansion_obs_{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # Store world facts with shared entities using retain_batch_async
-        # We need enough facts that semantic search won't return all of them as seeds
-        # Key: "Alice" query should find Alice's observation but NOT Bob's via semantic search
-        # Then graph retrieval should find Bob via shared "Python" entity
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                # Python developers - should be connected via "Python" entity
-                {
-                    "content": "Alice works with Python at TechCorp building REST APIs",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Alice"}, {"text": "TechCorp"}],
-                },
-                {
-                    "content": "Bob uses Python at DataSoft for machine learning models",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Bob"}, {"text": "DataSoft"}],
-                },
-                # Many unrelated facts to dilute semantic search and ensure
-                # "Alice" query only finds Alice-related content as seeds
-                {
-                    "content": "The weather in San Francisco is often foggy and cool",
-                    "context": "weather info",
-                    "entities": [{"text": "San Francisco"}],
-                },
-                {
-                    "content": "Tokyo is the capital city of Japan with many trains",
-                    "context": "geography info",
-                    "entities": [{"text": "Tokyo"}, {"text": "Japan"}],
-                },
-                {
-                    "content": "The Great Wall of China is a historic fortification",
-                    "context": "history info",
-                    "entities": [{"text": "Great Wall"}, {"text": "China"}],
-                },
-                {
-                    "content": "Coffee beans are grown in tropical regions worldwide",
-                    "context": "food info",
-                    "entities": [{"text": "Coffee"}],
-                },
-                {
-                    "content": "Electric vehicles are becoming more popular globally",
-                    "context": "technology info",
-                    "entities": [{"text": "Electric vehicles"}],
-                },
-                {
-                    "content": "The Amazon rainforest contains diverse wildlife species",
-                    "context": "nature info",
-                    "entities": [{"text": "Amazon"}, {"text": "Rainforest"}],
-                },
-                {
-                    "content": "Basketball is a popular sport in the United States",
-                    "context": "sports info",
-                    "entities": [{"text": "Basketball"}, {"text": "United States"}],
-                },
-                {
-                    "content": "Mozart composed many famous classical music pieces",
-                    "context": "music info",
-                    "entities": [{"text": "Mozart"}, {"text": "Classical music"}],
-                },
-            ],
-            request_context=request_context,
-        )
-
-        # Consolidation runs automatically after retain - wait for it to complete
-        # by querying for observations (consolidation creates them)
-        import asyncio
-        from hindsight_api.engine.memory_engine import Budget
-
-        # Wait for consolidation to complete with retry logic
-        # Consolidation runs as a background task and may take longer in CI
-        obs_result = None
-        for _ in range(30):  # Try up to 30 times (30 seconds max)
-            await asyncio.sleep(1)  # Wait 1 second between attempts
-            obs_result = await memory.recall_async(
-                bank_id=bank_id,
-                query="Python developer",
-                fact_type=["observation"],
-                budget=Budget.MID,
-                max_tokens=2048,
-                request_context=request_context,
-            )
-            if obs_result.results and len(obs_result.results) >= 1:
-                break
-
-        assert obs_result is not None and obs_result.results is not None, "Should have observations after consolidation"
-        # We should have observations from consolidation
-        assert len(obs_result.results) >= 1, f"Should have at least 1 observation about Python, got {len(obs_result.results)}"
-
-        # Now test graph retrieval specifically
-        # Query for Alice - should find Bob via shared "Python" entity
-        result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Alice",
-            fact_type=["observation"],
-            budget=Budget.MID,
-            max_tokens=2048,
-            enable_trace=True,
-            request_context=request_context,
-        )
-
-        # Verify graph retrieval is working by checking the internal debug logs
-        # The graph retrieval finds observations via entity links, but may not return
-        # NEW results if semantic search already found all connected observations.
-        # This is correct behavior - we verify the entity traversal path works.
-
-        # Check the trace for graph results
-        assert result.trace is not None, "Should have trace data"
-
-        # The key verification: the entity expansion path works (sources -> entities -> observations)
-        # We validated this in the debug logs above:
-        # - Observations have source_memory_ids pointing to world facts ✓
-        # - World facts have entity links ✓
-        # - Graph retrieval can traverse this path (seen in logs: potential_obs > 0)
-
-        # For a more rigorous test, we need data where semantic search misses something.
-        # Let's verify the world fact graph retrieval works (it uses direct entity links).
-        world_result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Alice",
-            fact_type=["world"],
-            budget=Budget.MID,
-            max_tokens=2048,
-            enable_trace=True,
-            request_context=request_context,
-        )
-
-        assert world_result.trace is not None, "Should have trace data for world facts"
-        world_retrieval_results = world_result.trace.get("retrieval_results", [])
-        world_graph_results = [
-            r for r in world_retrieval_results if r.get("method_name") == "graph"
-        ]
-
-        if world_graph_results:
-            world_graph_result = [r for r in world_graph_results if r.get("fact_type") == "world"][0]
-            world_graph_results_list = world_graph_result.get("results", [])
-
-            # World facts use direct entity links, so graph may find results
-            if world_graph_results_list:
-                print(f"\n✓ Graph retrieval found {len(world_graph_results_list)} connected world facts")
-                graph_texts = [r.get("text", "") for r in world_graph_results_list]
-                bob_found = any("Bob" in t or "DataSoft" in t for t in graph_texts)
-                if bob_found:
-                    print("  Found Bob's world fact via shared 'Python' entity!")
-
-        print("\n✓ Link expansion observation test passed!")
-        print("  Entity traversal path verified (observations -> sources -> entities -> connected sources -> observations)")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-
-@pytest.mark.asyncio
-async def test_link_expansion_world_fact_graph_retrieval(memory, request_context):
-    """
-    Test that world facts can find other world facts via shared entities.
-
-    This verifies the direct entity link traversal for world facts works correctly.
-    Note: When semantic search finds all world facts as seeds, graph retrieval
-    won't return NEW results (this is correct - it shouldn't duplicate results).
-    """
-    bank_id = f"test_link_expansion_world_{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # Store world facts with shared entities
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                # Python developers - should be connected via "Python" entity
-                {
-                    "content": "Alice works with Python at TechCorp building REST APIs",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Alice"}, {"text": "TechCorp"}],
-                },
-                {
-                    "content": "Bob uses Python at DataSoft for machine learning models",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Bob"}, {"text": "DataSoft"}],
-                },
-                # Unrelated facts
-                {
-                    "content": "The weather in San Francisco is often foggy",
-                    "context": "weather info",
-                    "entities": [{"text": "San Francisco"}],
-                },
-                {
-                    "content": "Coffee beans are grown in tropical regions",
-                    "context": "food info",
-                    "entities": [{"text": "Coffee"}],
-                },
-            ],
-            request_context=request_context,
-        )
-
-        from hindsight_api.engine.memory_engine import Budget
-
-        # Query for Alice
-        result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Alice",
-            fact_type=["world"],
-            budget=Budget.MID,
-            max_tokens=2048,
-            enable_trace=True,
-            request_context=request_context,
-        )
-
-        assert result.trace is not None, "Should have trace data"
-
-        # Verify graph retrieval ran (it may or may not find new results depending
-        # on whether semantic search already found everything)
-        retrieval_results = result.trace.get("retrieval_results", [])
-        graph_results = [
-            r for r in retrieval_results if r.get("method_name") == "graph"
-        ]
-        assert len(graph_results) > 0, "Should have graph retrieval results in trace"
-
-        # The important thing is that recall works and returns relevant results
-        assert result.results is not None and len(result.results) > 0, (
-            "Should return results for 'Alice' query"
-        )
-
-        # Alice's result should be at or near the top
-        result_texts = [r.text for r in result.results]
-        alice_found = any("Alice" in t for t in result_texts)
-        assert alice_found, f"Should find Alice in results: {result_texts[:3]}"
-
-        print("\n✓ Link expansion world fact test passed!")
-        print(f"  Recall returned {len(result.results)} results for 'Alice' query")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
@@ -1,10 +1,5 @@
 """
-Test LLM provider with different models using actual Hindsight memory operations.
-
-Tests validate that providers work correctly with:
-1. Retain (memory ingestion with fact extraction)
-2. Reflect (memory retrieval with tool calling)
-3. Mental models (consolidated knowledge generation)
+Test LLM provider with different models using actual memory operations.
 """
 import os
 from datetime import datetime
@@ -24,10 +19,6 @@ MODEL_MATRIX = [
    ("openai", "gpt-5-nano"),
    ("openai", "gpt-5"),
    ("openai", "gpt-5.2"),
-    # Anthropic models
-    ("anthropic", "claude-sonnet-4-20250514"),
-    ("anthropic", "claude-opus-4-5-20251101"),
-    ("anthropic", "claude-haiku-4-20250514"),
    # Groq models
    ("groq", "openai/gpt-oss-120b"),
    ("groq", "openai/gpt-oss-20b"),
@@ -38,12 +29,6 @@ MODEL_MATRIX = [
    # Ollama models (local)
    ("ollama", "gemma3:12b"),
    ("ollama", "gemma3:1b"),
-    # Claude Code (uses Claude Agent SDK with Claude models)
-    ("claude-code", "claude-sonnet-4-20250514"),
-    # OpenAI Codex (uses MCP with Codex-specific models)
-    ("openai-codex", "gpt-5.2-codex"),
-    # Mock provider (for testing)
-    ("mock", "mock"),
 ]


@@ -51,7 +36,6 @@ def get_api_key_for_provider(provider: str) -> str | None:
    """Get API key for provider from environment variables."""
    provider_key_map = {
        "openai": "OPENAI_API_KEY",
-        "anthropic": "ANTHROPIC_API_KEY",
        "groq": "GROQ_API_KEY",
        "gemini": "GEMINI_API_KEY",
    }
@@ -59,171 +43,6 @@ def get_api_key_for_provider(provider: str) -> str | None:
    return os.getenv(env_var) if env_var else None


-def should_skip_provider(provider: str, model: str = "") -> tuple[bool, str]:
-    """Check if provider should be skipped and return reason."""
-    # Never skip mock provider
-    if provider == "mock":
-        return False, ""
-
-    # Skip claude-code and openai-codex in CI (require local auth)
-    if os.getenv("CI") and provider in ("claude-code", "openai-codex"):
-        return True, f"{provider} not available in CI (requires local authentication)"
-
-    # Skip Ollama in CI (no models available)
-    if provider == "ollama" and os.getenv("CI"):
-        return True, "Ollama not available in CI"
-
-    # Skip Ollama gemma models (don't support tool calling)
-    if provider == "ollama" and "gemma" in model.lower():
-        return True, f"Ollama {model} does not support tool calling"
-
-    # Other providers need an API key
-    if provider not in ("ollama", "claude-code", "openai-codex", "mock"):
-        api_key = get_api_key_for_provider(provider)
-        if not api_key:
-            return True, f"No API key available (set {provider.upper()}_API_KEY)"
-
-    return False, ""
-
-
-@pytest.mark.parametrize("provider,model", MODEL_MATRIX)
-@pytest.mark.asyncio
-@pytest.mark.timeout(300)  # Increase timeout for slow models like groq gpt-oss-120b
-async def test_llm_provider_api_methods(provider: str, model: str):
-    """
-    Test all LLM API methods used by Hindsight at runtime.
-    This validates that the provider correctly implements the LLMInterface.
-
-    Tests:
-    1. verify_connection() - Connection verification
-    2. call() with plain text - Basic LLM call
-    3. call() with response_format - Structured output (used in fact extraction)
-    4. call_with_tools() - Tool calling (used in reflect agent)
-    """
-    # Skip mock provider - it's a test stub, not a real LLM implementation
-    if provider == "mock":
-        pytest.skip("Mock provider is a test stub, not a real LLM")
-
-    should_skip, reason = should_skip_provider(provider, model)
-    if should_skip:
-        pytest.skip(f"Skipping {provider}/{model}: {reason}")
-
-    api_key = get_api_key_for_provider(provider)
-
-    llm = LLMProvider(
-        provider=provider,
-        api_key=api_key or "",
-        base_url="",
-        model=model,
-    )
-
-    print(f"\n{provider}/{model} - API methods test:")
-
-    # Test 1: verify_connection()
-    try:
-        await llm.verify_connection()
-        print("  ✓ verify_connection()")
-    except Exception as e:
-        pytest.fail(f"{provider}/{model} verify_connection() failed: {e}")
-
-    # Test 2: call() with plain text
-    try:
-        response = await llm.call(
-            messages=[
-                {"role": "system", "content": "You are a helpful assistant."},
-                {"role": "user", "content": "What is 2+2? Answer in one word."},
-            ],
-            max_completion_tokens=50,
-        )
-        assert response is not None, "call() returned None"
-        assert len(response) > 0, "call() returned empty string"
-        print(f"  ✓ call() plain text: {response[:50]}")
-    except Exception as e:
-        pytest.fail(f"{provider}/{model} call() plain text failed: {e}")
-
-    # Test 3: call() with response_format (structured output)
-    # Skip for models that don't support structured output
-    skip_structured_output = (provider == "groq" and "gpt-oss-120b" in model.lower())
-    if skip_structured_output:
-        print(f"  ⊘ call() structured output: skipped (model doesn't support response_format)")
-    else:
-        try:
-            from pydantic import BaseModel
-
-            class TestResponse(BaseModel):
-                answer: str
-                confidence: str
-
-            response = await llm.call(
-                messages=[
-                    {"role": "system", "content": "You are a math assistant."},
-                    {"role": "user", "content": "What is the capital of France?"},
-                ],
-                response_format=TestResponse,
-                max_completion_tokens=100,
-            )
-            assert isinstance(response, TestResponse), f"Expected TestResponse, got {type(response)}"
-            assert hasattr(response, "answer"), "Structured output missing 'answer' field"
-            assert hasattr(response, "confidence"), "Structured output missing 'confidence' field"
-            print(f"  ✓ call() structured output: answer={response.answer}, confidence={response.confidence}")
-        except Exception as e:
-            pytest.fail(f"{provider}/{model} call() structured output failed: {e}")
-
-    # Test 4: call_with_tools() (tool calling)
-    try:
-        tools = [
-            {
-                "type": "function",
-                "function": {
-                    "name": "get_weather",
-                    "description": "Get the weather for a location",
-                    "parameters": {
-                        "type": "object",
-                        "properties": {
-                            "location": {"type": "string", "description": "City name"},
-                            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
-                        },
-                        "required": ["location"],
-                    },
-                },
-            }
-        ]
-
-        result = await llm.call_with_tools(
-            messages=[
-                {"role": "system", "content": "You are a helpful assistant with access to tools."},
-                {"role": "user", "content": "What's the weather like in Paris?"},
-            ],
-            tools=tools,
-            max_completion_tokens=500,  # Increased from 200 to give models enough space for tool calls
-        )
-
-        assert result is not None, "call_with_tools() returned None"
-        assert hasattr(result, "tool_calls"), "Result missing 'tool_calls' attribute"
-
-        # Nano models may hit token limits before making tool calls - that's acceptable
-        is_nano_model = "nano" in model.lower()
-        if is_nano_model and len(result.tool_calls) == 0:
-            # Check if it hit length limit (expected for nano models)
-            if hasattr(result, "finish_reason") and result.finish_reason == "length":
-                print(f"  ✓ call_with_tools(): nano model hit token limit (expected)")
-            else:
-                pytest.fail(f"Nano model made 0 tool calls but didn't hit length limit (finish_reason={getattr(result, 'finish_reason', 'unknown')})")
-        else:
-            assert len(result.tool_calls) > 0, f"Expected at least 1 tool call, got {len(result.tool_calls)}"
-
-            # Verify tool call structure
-            tool_call = result.tool_calls[0]
-            assert hasattr(tool_call, "name"), "Tool call missing 'name'"
-            assert hasattr(tool_call, "arguments"), "Tool call missing 'arguments'"
-            assert tool_call.name == "get_weather", f"Expected 'get_weather', got '{tool_call.name}'"
-            assert "location" in tool_call.arguments, "Tool call arguments missing 'location'"
-
-            print(f"  ✓ call_with_tools(): {tool_call.name}({tool_call.arguments})")
-    except Exception as e:
-        pytest.fail(f"{provider}/{model} call_with_tools() failed: {e}")
-
-
@pytest.mark.parametrize("provider,model", MODEL_MATRIX)
@pytest.mark.asyncio
 async def test_llm_provider_memory_operations(provider: str, model: str):
@@ -231,16 +50,16 @@ async def test_llm_provider_memory_operations(provider: str, model: str):
    Test LLM provider with actual memory operations: fact extraction and reflect.
    All models must pass this test.
    """
-    # Skip mock provider - it's a test stub, not designed for real operations
-    if provider == "mock":
-        pytest.skip("Mock provider is a test stub, not designed for real operations")
-
-    should_skip, reason = should_skip_provider(provider, model)
-    if should_skip:
-        pytest.skip(f"Skipping {provider}/{model}: {reason}")
-
    api_key = get_api_key_for_provider(provider)

+    # Skip Ollama tests in CI (no models available)
+    if provider == "ollama" and os.getenv("CI"):
+        pytest.skip(f"Skipping {provider}/{model}: Ollama not available in CI")
+
+    # Other providers need an API key
+    if provider != "ollama" and not api_key:
+        pytest.skip(f"Skipping {provider}/{model}: no API key available")
+
    llm = LLMProvider(
        provider=provider,
        api_key=api_key or "",
@@ -298,115 +117,3 @@ async def test_llm_provider_memory_operations(provider: str, model: str):

    assert response is not None, f"{provider}/{model} reflect returned None"
    assert len(response) > 10, f"{provider}/{model} reflect response too short"
-
-
-@pytest.mark.parametrize("provider,model", [
-    ("claude-code", "claude-sonnet-4-20250514"),
-    ("openai-codex", "gpt-5.2-codex"),
-])
-@pytest.mark.asyncio
-async def test_llm_provider_consolidation(memory_no_llm_verify, request_context, provider: str, model: str):
-    """
-    Test LLM provider with consolidation (automatic mental model generation from observations).
-    This validates that the provider can generate synthesized knowledge from raw memories.
-
-    This test is limited to claude-code and codex since they're the critical providers
-    that needed tool calling fixes for reflect and consolidation operations.
-    """
-    should_skip, reason = should_skip_provider(provider, model)
-    if should_skip:
-        pytest.skip(f"Skipping {provider}/{model}: {reason}")
-
-    # Use provider-specific LLM for this test
-    api_key = get_api_key_for_provider(provider)
-    memory_no_llm_verify._consolidation_llm = LLMProvider(
-        provider=provider,
-        api_key=api_key or "",
-        base_url="",
-        model=model,
-    )
-    # Also need retain LLM for ingesting data
-    memory_no_llm_verify._retain_llm = memory_no_llm_verify._consolidation_llm
-
-    test_bank_id = f"llm_test_consolidation_{provider}_{model}_{datetime.now().timestamp()}"
-
-    # Enable observations for this bank
-    from hindsight_api.config import get_config
-    config = get_config()
-    original_value = config.enable_observations
-    config.enable_observations = True
-
-    try:
-        # Retain memories to consolidate
-        test_content = """
-        Bob prefers functional programming with Rust and Haskell.
-        He emphasizes immutability and pure functions in code reviews.
-        Bob advocates for type safety and compile-time guarantees.
-        He avoids mutable state and prefers declarative code patterns.
-        """
-
-        await memory_no_llm_verify.retain_async(
-            bank_id=test_bank_id,
-            content=test_content,
-            context="Team coding preferences",
-            event_date=datetime(2024, 12, 1),
-            request_context=request_context,
-        )
-
-        print(f"\n{provider}/{model} - Consolidation test:")
-
-        # Run consolidation to generate observations (mental models)
-        from hindsight_api.engine.consolidation.consolidator import run_consolidation_job
-
-        result = await run_consolidation_job(
-            memory_engine=memory_no_llm_verify,
-            bank_id=test_bank_id,
-            request_context=request_context,
-        )
-
-        print(f"  Processed: {result.get('memories_processed', 0)} memories")
-        print(f"  Created: {result.get('observations_created', 0)} observations")
-        print(f"  Updated: {result.get('observations_updated', 0)} observations")
-
-        # Verify consolidation ran successfully
-        assert result["status"] in ["success", "no_new_memories"], f"{provider}/{model} consolidation failed"
-
-        # If observations were created, verify they contain relevant content
-        if result.get("observations_created", 0) > 0:
-            observations = await memory_no_llm_verify.list_mental_models_consolidated(
-                bank_id=test_bank_id,
-                request_context=request_context,
-            )
-
-            assert len(observations) > 0, f"{provider}/{model} consolidation created 0 observations"
-
-            # Check first observation contains relevant information
-            obs_content = observations[0].get("content", "").lower()
-            relevant_terms = ["bob", "functional", "rust", "immutab", "type"]
-            matches = [term for term in relevant_terms if term in obs_content]
-
-            print(f"  Observation preview: {observations[0].get('content', '')[:200]}...")
-            print(f"  Found {len(matches)} relevant terms: {matches}")
-
-            assert len(matches) >= 2, (
-                f"{provider}/{model} consolidated observation doesn't contain relevant info. "
-                f"Expected at least 2 of {relevant_terms}, found {len(matches)}: {matches}"
-            )
-
-    finally:
-        # Restore original config
-        config.enable_observations = original_value
-
-
-# NOTE: The tests above validate the critical Hindsight operations:
-#
-# test_llm_provider_memory_operations (ALL providers):
-#   - Fact extraction (retain): tests structured output generation
-#   - Reflect: tests memory retrieval and reasoning (uses tool calling for claude-code/codex)
-#
-# test_llm_provider_consolidation (claude-code and codex only):
-#   - Consolidation: tests automatic mental model generation from observations
-#   - Requires MemoryEngine fixture with working LLM (from .env or env vars)
-#   - Run your local LLM server OR set HINDSIGHT_API_LLM_PROVIDER/API_KEY/MODEL env vars
-#
-# For full end-to-end integration tests using the HTTP API, see tests/test_http_api_integration.py
@@ -30,8 +30,7 @@ async def test_llm_metrics_recorded_for_groq():
    # Create a mock metrics collector to track record_llm_call calls
    mock_collector = MagicMock(spec=MetricsCollector)

-    # Patch the provider module where get_metrics_collector is actually called
-    with patch("hindsight_api.engine.providers.openai_compatible_llm.get_metrics_collector", return_value=mock_collector):
+    with patch("hindsight_api.engine.llm_wrapper.get_metrics_collector", return_value=mock_collector):
        llm = LLMProvider(
            provider="groq",
            api_key=api_key,
@@ -91,8 +90,7 @@ async def test_llm_metrics_recorded_for_structured_output():

    mock_collector = MagicMock(spec=MetricsCollector)

-    # Patch the provider module where get_metrics_collector is actually called
-    with patch("hindsight_api.engine.providers.openai_compatible_llm.get_metrics_collector", return_value=mock_collector):
+    with patch("hindsight_api.engine.llm_wrapper.get_metrics_collector", return_value=mock_collector):
        llm = LLMProvider(
            provider="groq",
            api_key=api_key,
@@ -241,8 +241,8 @@ class TestReflectToolSchemas:
        tools = get_reflect_tools()

        tool_names = [t["function"]["name"] for t in tools]
+        assert "search_reflections" in tool_names
        assert "search_mental_models" in tool_names
-        assert "search_observations" in tool_names
        assert "recall" in tool_names
        assert "expand" in tool_names
        assert "done" in tool_names
@@ -273,8 +273,8 @@ class TestReflectToolSchemas:

        assert "answer" in params
        assert "memory_ids" in params
-        assert "observation_ids" in params
        assert "mental_model_ids" in params
+        assert "reflection_ids" in params


 class TestLLMToolCallResult:
@@ -1,78 +0,0 @@
-"""Integration test for MCP endpoint routing.
-
-This test verifies that /mcp/ and /mcp/{bank_id}/ expose different tool sets.
-"""
-
-import httpx
-import pytest
-from mcp.client.session import ClientSession
-from mcp.client.streamable_http import streamable_http_client
-
-
-@pytest.mark.asyncio
-async def test_mcp_endpoint_routing_integration(memory):
-    """Test that multi-bank and single-bank endpoints expose different tools using StreamableHTTP.
-
-    This is a regression test for issue #317 where /mcp/{bank_id}/ was incorrectly
-    exposing all tools (including list_banks) and bank_id parameters.
-    """
-    from hindsight_api.api import create_app
-
-    # Create app with MCP enabled
-    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
-
-    # Use the app's lifespan context to properly initialize MCP servers
-    async with app.router.lifespan_context(app):
-        # Create an HTTPX client that routes to our ASGI app
-        from httpx import ASGITransport
-
-        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
-            # Test 1: Multi-bank endpoint /mcp/
-            async with streamable_http_client("http://test/mcp/", http_client=http_client) as (
-                read_stream,
-                write_stream,
-                _,
-            ):
-                async with ClientSession(read_stream, write_stream) as session:
-                    await session.initialize()
-                    multi_result = await session.list_tools()
-
-                    multi_tools = {t.name for t in multi_result.tools}
-
-                    # Multi-bank should have all tools including bank management
-                    assert "retain" in multi_tools
-                    assert "recall" in multi_tools
-                    assert "reflect" in multi_tools
-                    assert "list_banks" in multi_tools, "Multi-bank should expose list_banks"
-                    assert "create_bank" in multi_tools, "Multi-bank should expose create_bank"
-
-                    # Multi-bank retain should have bank_id parameter
-                    retain_tool = next((t for t in multi_result.tools if t.name == "retain"), None)
-                    assert retain_tool is not None
-                    multi_params = set(retain_tool.inputSchema.get("properties", {}).keys())
-                    assert "bank_id" in multi_params, "Multi-bank retain should have bank_id parameter"
-
-            # Test 2: Single-bank endpoint /mcp/test-bank/
-            async with streamable_http_client("http://test/mcp/test-bank/", http_client=http_client) as (
-                read_stream,
-                write_stream,
-                _,
-            ):
-                async with ClientSession(read_stream, write_stream) as session:
-                    await session.initialize()
-                    single_result = await session.list_tools()
-
-                    single_tools = {t.name for t in single_result.tools}
-
-                    # Single-bank should only have scoped tools (no bank management)
-                    assert "retain" in single_tools
-                    assert "recall" in single_tools
-                    assert "reflect" in single_tools
-                    assert "list_banks" not in single_tools, "Single-bank should NOT expose list_banks"
-                    assert "create_bank" not in single_tools, "Single-bank should NOT expose create_bank"
-
-                    # Single-bank retain should NOT have bank_id parameter
-                    retain_tool = next((t for t in single_result.tools if t.name == "retain"), None)
-                    assert retain_tool is not None
-                    single_params = set(retain_tool.inputSchema.get("properties", {}).keys())
-                    assert "bank_id" not in single_params, "Single-bank retain should NOT have bank_id parameter"
@@ -1,169 +0,0 @@
-"""Tests for MCPExtension loading and tool registration."""
-
-from unittest.mock import MagicMock, patch
-
-import pytest
-from fastmcp import FastMCP
-
-from hindsight_api import MemoryEngine
-from hindsight_api.extensions.mcp import MCPExtension
-
-
-class MockMCPExtension(MCPExtension):
-    """Test extension that registers a custom tool."""
-
-    def __init__(self, config=None):
-        super().__init__(config)
-        self.register_tools_called = False
-        self.registered_mcp = None
-        self.registered_memory = None
-
-    def register_tools(self, mcp: FastMCP, memory: MemoryEngine) -> None:
-        """Register a test tool to verify extension was called."""
-        self.register_tools_called = True
-        self.registered_mcp = mcp
-        self.registered_memory = memory
-
-        @mcp.tool()
-        async def test_extension_tool(query: str) -> str:
-            """A test tool registered by the extension."""
-            return f"Extension tool received: {query}"
-
-
-class TestMCPExtensionBase:
-    """Tests for MCPExtension base class."""
-
-    def test_mcp_extension_is_abstract(self):
-        """MCPExtension.register_tools is abstract and must be implemented."""
-        with pytest.raises(TypeError, match="abstract method"):
-            MCPExtension()
-
-    def test_subclass_can_be_instantiated(self):
-        """Subclass implementing register_tools can be instantiated."""
-        ext = MockMCPExtension()
-        assert ext is not None
-        assert ext.register_tools_called is False
-
-    def test_register_tools_receives_mcp_and_memory(self):
-        """register_tools receives FastMCP and MemoryEngine instances."""
-        ext = MockMCPExtension()
-        mcp = FastMCP("test")
-        memory = MagicMock(spec=MemoryEngine)
-
-        ext.register_tools(mcp, memory)
-
-        assert ext.register_tools_called is True
-        assert ext.registered_mcp is mcp
-        assert ext.registered_memory is memory
-
-
-class TestMCPExtensionLoading:
-    """Tests for MCPExtension loading in create_mcp_server."""
-
-    @pytest.fixture
-    def mock_memory(self):
-        """Create a mock MemoryEngine."""
-        memory = MagicMock()
-        memory._tenant_extension = MagicMock()
-        memory._tenant_extension.authenticate_mcp = MagicMock()
-        return memory
-
-    def test_create_mcp_server_without_extension(self, mock_memory):
-        """create_mcp_server works without MCPExtension configured."""
-        from hindsight_api.api.mcp import create_mcp_server
-
-        with patch("hindsight_api.api.mcp.load_extension", return_value=None):
-            mcp = create_mcp_server(mock_memory)
-
-        # Core tools should be registered
-        tools = mcp._tool_manager._tools
-        assert "retain" in tools
-        assert "recall" in tools
-        assert "reflect" in tools
-        # Extension tool should NOT be present
-        assert "test_extension_tool" not in tools
-
-    def test_create_mcp_server_with_extension(self, mock_memory):
-        """create_mcp_server loads and calls MCPExtension when configured."""
-        from hindsight_api.api.mcp import create_mcp_server
-
-        mock_ext = MockMCPExtension()
-
-        with patch("hindsight_api.api.mcp.load_extension", return_value=mock_ext):
-            mcp = create_mcp_server(mock_memory)
-
-        # Extension should have been called
-        assert mock_ext.register_tools_called is True
-
-        # Core tools should still be registered
-        tools = mcp._tool_manager._tools
-        assert "retain" in tools
-        assert "recall" in tools
-
-        # Extension tool should also be registered
-        assert "test_extension_tool" in tools
-
-    @pytest.mark.asyncio
-    async def test_extension_tool_is_callable(self, mock_memory):
-        """Tool registered by extension can be called."""
-        from hindsight_api.api.mcp import create_mcp_server
-
-        mock_ext = MockMCPExtension()
-
-        with patch("hindsight_api.api.mcp.load_extension", return_value=mock_ext):
-            mcp = create_mcp_server(mock_memory)
-
-        # Get and call the extension tool
-        tools = mcp._tool_manager._tools
-        test_tool = tools["test_extension_tool"]
-        result = await test_tool.fn(query="hello world")
-
-        assert result == "Extension tool received: hello world"
-
-    def test_load_extension_called_with_correct_args(self, mock_memory):
-        """load_extension is called with 'MCP' prefix and MCPExtension class."""
-        from hindsight_api.api.mcp import create_mcp_server
-
-        with patch("hindsight_api.api.mcp.load_extension") as mock_load:
-            mock_load.return_value = None
-            create_mcp_server(mock_memory)
-
-        mock_load.assert_called_once_with("MCP", MCPExtension)
-
-
-class TestMCPExtensionIntegration:
-    """Integration tests verifying extension tools work end-to-end."""
-
-    @pytest.fixture
-    def mock_memory(self):
-        """Create a mock MemoryEngine with required methods."""
-        memory = MagicMock()
-        memory.retain_batch_async = MagicMock()
-        memory.submit_async_retain = MagicMock(return_value={"operation_id": "test-op"})
-        memory.recall_async = MagicMock(return_value=MagicMock(results=[]))
-        memory.reflect_async = MagicMock(return_value=MagicMock(text="reflection"))
-        memory.list_banks = MagicMock(return_value=[])
-        memory.get_bank_profile = MagicMock(return_value={"id": "test"})
-        memory._tenant_extension = MagicMock()
-        return memory
-
-    def test_extension_tools_coexist_with_core_tools(self, mock_memory):
-        """Extension tools are added alongside core tools, not replacing them."""
-        from hindsight_api.api.mcp import create_mcp_server
-
-        mock_ext = MockMCPExtension()
-
-        with patch("hindsight_api.api.mcp.load_extension", return_value=mock_ext):
-            mcp = create_mcp_server(mock_memory)
-
-        tools = mcp._tool_manager._tools
-        # All core tools present
-        assert "retain" in tools
-        assert "recall" in tools
-        assert "reflect" in tools
-        assert "list_banks" in tools
-        assert "create_bank" in tools
-        # Extension tool also present
-        assert "test_extension_tool" in tools
-        # Total: 5 core + 1 extension = 6 tools
-        assert len(tools) == 6
@@ -97,196 +97,3 @@ def test_path_parsing_logic():
    bank_id, remaining = parse_path("/my-bank/some/path")
    assert bank_id == "my-bank"
    assert remaining == "/some/path"
-
-
-@pytest.mark.asyncio
-async def test_api_key_context_variable():
-    """Test that API key context variable works correctly."""
-    from hindsight_api.api.mcp import get_current_api_key, _current_api_key
-
-    # Initially None
-    assert get_current_api_key() is None
-
-    # Set and verify
-    token = _current_api_key.set("test-api-key-123")
-    try:
-        assert get_current_api_key() == "test-api-key-123"
-    finally:
-        _current_api_key.reset(token)
-
-    # Back to None after reset
-    assert get_current_api_key() is None
-
-
-@pytest.mark.asyncio
-async def test_mcp_tools_propagate_api_key(mock_memory):
-    """Test that MCP tools propagate API key to RequestContext."""
-    from hindsight_api.api.mcp import create_mcp_server, _current_bank_id, _current_api_key
-
-    mcp_server = create_mcp_server(mock_memory)
-    tools = mcp_server._tool_manager._tools
-
-    # Set both bank_id and api_key context
-    bank_token = _current_bank_id.set("test-bank")
-    api_key_token = _current_api_key.set("test-bearer-token")
-    try:
-        retain_tool = tools["retain"]
-        result = await retain_tool.fn(content="test content", context="test_context", async_processing=False)
-        assert "successfully" in result.lower()
-
-        # Verify the memory was called with request_context containing api_key
-        mock_memory.retain_batch_async.assert_called_once()
-        call_kwargs = mock_memory.retain_batch_async.call_args.kwargs
-        assert call_kwargs["request_context"].api_key == "test-bearer-token"
-    finally:
-        _current_bank_id.reset(bank_token)
-        _current_api_key.reset(api_key_token)
-
-
-def test_multi_bank_mode_exposes_all_tools(mock_memory):
-    """Test that multi-bank mode exposes all tools including bank management."""
-    from hindsight_api.api.mcp import create_mcp_server
-
-    # Create server in multi-bank mode (default)
-    mcp_server = create_mcp_server(mock_memory, multi_bank=True)
-    tools = mcp_server._tool_manager._tools
-
-    # Should have all tools
-    assert "retain" in tools
-    assert "recall" in tools
-    assert "reflect" in tools
-    assert "list_banks" in tools
-    assert "create_bank" in tools
-
-
-def test_single_bank_mode_excludes_bank_management_tools(mock_memory):
-    """Test that single-bank mode only exposes bank-scoped tools."""
-    from hindsight_api.api.mcp import create_mcp_server
-
-    # Create server in single-bank mode
-    mcp_server = create_mcp_server(mock_memory, multi_bank=False)
-    tools = mcp_server._tool_manager._tools
-
-    # Should only have bank-scoped tools
-    assert "retain" in tools
-    assert "recall" in tools
-    assert "reflect" in tools
-
-    # Should NOT have bank management tools
-    assert "list_banks" not in tools
-    assert "create_bank" not in tools
-
-
-def test_multi_bank_mode_tools_have_bank_id_param(mock_memory):
-    """Test that multi-bank mode tools include bank_id parameter."""
-    from hindsight_api.api.mcp import create_mcp_server
-    import inspect
-
-    mcp_server = create_mcp_server(mock_memory, multi_bank=True)
-    tools = mcp_server._tool_manager._tools
-
-    # Check that tools have bank_id parameter
-    retain_tool = tools["retain"]
-    retain_sig = inspect.signature(retain_tool.fn)
-    assert "bank_id" in retain_sig.parameters
-
-    recall_tool = tools["recall"]
-    recall_sig = inspect.signature(recall_tool.fn)
-    assert "bank_id" in recall_sig.parameters
-
-    reflect_tool = tools["reflect"]
-    reflect_sig = inspect.signature(reflect_tool.fn)
-    assert "bank_id" in reflect_sig.parameters
-
-
-def test_single_bank_mode_tools_no_bank_id_param(mock_memory):
-    """Test that single-bank mode tools do NOT include bank_id parameter."""
-    from hindsight_api.api.mcp import create_mcp_server
-    import inspect
-
-    mcp_server = create_mcp_server(mock_memory, multi_bank=False)
-    tools = mcp_server._tool_manager._tools
-
-    # Check that tools do NOT have bank_id parameter
-    retain_tool = tools["retain"]
-    retain_sig = inspect.signature(retain_tool.fn)
-    assert "bank_id" not in retain_sig.parameters
-
-    recall_tool = tools["recall"]
-    recall_sig = inspect.signature(recall_tool.fn)
-    assert "bank_id" not in recall_sig.parameters
-
-    reflect_tool = tools["reflect"]
-    reflect_sig = inspect.signature(reflect_tool.fn)
-    assert "bank_id" not in reflect_sig.parameters
-
-
-@pytest.mark.asyncio
-async def test_middleware_handles_both_endpoints(mock_memory):
-    """Test that MCPMiddleware routes to correct server based on URL path."""
-    from hindsight_api.api.mcp import MCPMiddleware
-
-    # Create middleware (single instance)
-    middleware = MCPMiddleware(None, mock_memory)
-
-    # Verify both server instances exist
-    assert middleware.multi_bank_app is not None
-    assert middleware.single_bank_app is not None
-
-    # Verify they expose different tools
-    multi_bank_tools = middleware.multi_bank_server._tool_manager._tools
-    single_bank_tools = middleware.single_bank_server._tool_manager._tools
-
-    # Multi-bank should have all tools
-    assert "retain" in multi_bank_tools
-    assert "recall" in multi_bank_tools
-    assert "list_banks" in multi_bank_tools
-    assert "create_bank" in multi_bank_tools
-
-    # Single-bank should only have scoped tools
-    assert "retain" in single_bank_tools
-    assert "recall" in single_bank_tools
-    assert "list_banks" not in single_bank_tools
-    assert "create_bank" not in single_bank_tools
-
-
-@pytest.mark.asyncio
-async def test_routing_logic_from_url_path():
-    """Test that routing correctly selects server based on URL structure."""
-    from hindsight_api.api.mcp import MCPMiddleware
-    from unittest.mock import AsyncMock
-
-    # Mock memory
-    mock_memory = MagicMock()
-
-    # Create middleware
-    middleware = MCPMiddleware(None, mock_memory)
-
-    # Simulate different URL patterns and verify routing
-    test_cases = [
-        # (path_after_stripping_mcp, expected_bank_id_from_path, expected_bank_id, description)
-        ("/alice/messages", True, "alice", "Bank ID in path with endpoint"),
-        ("/my-agent-123/", True, "my-agent-123", "Bank ID in path with trailing slash"),
-        ("ciccio/messages", True, "ciccio", "Bank ID without leading slash (after mount strip)"),
-        ("bob", True, "bob", "Bank ID only, no leading slash"),
-        ("/messages", False, None, "MCP endpoint, no bank ID"),
-        ("/", False, None, "Root path, no bank ID"),
-    ]
-
-    for path, expected_bank_from_path, expected_bank_id, description in test_cases:
-        # Simulate the path parsing logic with leading slash normalization
-        if path and not path.startswith("/"):
-            path = "/" + path
-
-        bank_id = None
-        bank_id_from_path = False
-        MCP_ENDPOINTS = {"sse", "messages"}
-
-        if path.startswith("/") and len(path) > 1:
-            parts = path[1:].split("/", 1)
-            if parts[0] and parts[0] not in MCP_ENDPOINTS:
-                bank_id = parts[0]
-                bank_id_from_path = True
-
-        assert bank_id_from_path == expected_bank_from_path, f"Failed for: {description} (path={path})"
-        assert bank_id == expected_bank_id, f"Failed bank_id for: {description} (path={path}, got={bank_id})"
@@ -1,206 +0,0 @@
-"""Unit tests for mental model operation validator hooks.
-
-Tests that the operation validator hooks are called correctly for
-mental model GET and refresh operations.
-"""
-
-import pytest
-
-from hindsight_api.extensions.operation_validator import (
-    MentalModelGetContext,
-    MentalModelGetResult,
-    MentalModelRefreshResult,
-    OperationValidatorExtension,
-    ValidationResult,
-)
-
-
-class TestMentalModelGetContextDataclass:
-    """Tests for MentalModelGetContext dataclass."""
-
-    def test_create_context(self):
-        """Test creating a MentalModelGetContext."""
-        from unittest.mock import MagicMock
-
-        request_context = MagicMock()
-        ctx = MentalModelGetContext(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=request_context,
-        )
-
-        assert ctx.bank_id == "bank-1"
-        assert ctx.mental_model_id == "mm-1"
-        assert ctx.request_context is request_context
-
-
-class TestMentalModelGetResultDataclass:
-    """Tests for MentalModelGetResult dataclass."""
-
-    def test_create_result_success(self):
-        """Test creating a successful MentalModelGetResult."""
-        from unittest.mock import MagicMock
-
-        request_context = MagicMock()
-        result = MentalModelGetResult(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=request_context,
-            output_tokens=250,
-        )
-
-        assert result.bank_id == "bank-1"
-        assert result.mental_model_id == "mm-1"
-        assert result.output_tokens == 250
-        assert result.success is True
-        assert result.error is None
-
-    def test_create_result_failure(self):
-        """Test creating a failed MentalModelGetResult."""
-        from unittest.mock import MagicMock
-
-        result = MentalModelGetResult(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=MagicMock(),
-            output_tokens=0,
-            success=False,
-            error="Not found",
-        )
-
-        assert result.success is False
-        assert result.error == "Not found"
-
-
-class TestMentalModelRefreshResultDataclass:
-    """Tests for MentalModelRefreshResult dataclass."""
-
-    def test_create_result_with_all_fields(self):
-        """Test creating a MentalModelRefreshResult with all fields."""
-        from unittest.mock import MagicMock
-
-        result = MentalModelRefreshResult(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=MagicMock(),
-            query_tokens=50,
-            output_tokens=500,
-            context_tokens=0,
-            facts_used=10,
-            mental_models_used=2,
-        )
-
-        assert result.query_tokens == 50
-        assert result.output_tokens == 500
-        assert result.context_tokens == 0
-        assert result.facts_used == 10
-        assert result.mental_models_used == 2
-        assert result.success is True
-        assert result.error is None
-
-    def test_create_result_failure(self):
-        """Test creating a failed MentalModelRefreshResult."""
-        from unittest.mock import MagicMock
-
-        result = MentalModelRefreshResult(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=MagicMock(),
-            query_tokens=50,
-            output_tokens=0,
-            context_tokens=0,
-            facts_used=0,
-            mental_models_used=0,
-            success=False,
-            error="Reflect failed",
-        )
-
-        assert result.success is False
-        assert result.error == "Reflect failed"
-
-
-class TestDefaultHookBehavior:
-    """Tests for default (no-op) behavior of mental model hooks on OperationValidatorExtension."""
-
-    @pytest.fixture
-    def validator(self):
-        """Create a concrete subclass for testing default behavior."""
-        from unittest.mock import MagicMock
-
-        # Create a concrete subclass that implements the abstract methods
-        class TestValidator(OperationValidatorExtension):
-            async def validate_retain(self, ctx):
-                return ValidationResult.accept()
-
-            async def validate_recall(self, ctx):
-                return ValidationResult.accept()
-
-            async def validate_reflect(self, ctx):
-                return ValidationResult.accept()
-
-        return TestValidator(config={})
-
-    @pytest.mark.asyncio
-    async def test_validate_mental_model_get_default_accepts(self, validator):
-        """Test that default validate_mental_model_get accepts."""
-        from unittest.mock import MagicMock
-
-        ctx = MentalModelGetContext(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=MagicMock(),
-        )
-
-        result = await validator.validate_mental_model_get(ctx)
-
-        assert result.allowed is True
-
-    @pytest.mark.asyncio
-    async def test_on_mental_model_get_complete_default_noop(self, validator):
-        """Test that default on_mental_model_get_complete is a no-op."""
-        from unittest.mock import MagicMock
-
-        result = MentalModelGetResult(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=MagicMock(),
-            output_tokens=100,
-        )
-
-        # Should not raise
-        await validator.on_mental_model_get_complete(result)
-
-    @pytest.mark.asyncio
-    async def test_on_mental_model_refresh_complete_default_noop(self, validator):
-        """Test that default on_mental_model_refresh_complete is a no-op."""
-        from unittest.mock import MagicMock
-
-        result = MentalModelRefreshResult(
-            bank_id="bank-1",
-            mental_model_id="mm-1",
-            request_context=MagicMock(),
-            query_tokens=50,
-            output_tokens=500,
-            context_tokens=0,
-            facts_used=5,
-            mental_models_used=1,
-        )
-
-        # Should not raise
-        await validator.on_mental_model_refresh_complete(result)
-
-
-class TestExportsAvailable:
-    """Test that mental model hooks are properly exported."""
-
-    def test_imports_from_extensions_package(self):
-        """Test that all mental model types can be imported from hindsight_api.extensions."""
-        from hindsight_api.extensions import (
-            MentalModelGetContext,
-            MentalModelGetResult,
-            MentalModelRefreshResult,
-        )
-
-        assert MentalModelGetContext is not None
-        assert MentalModelGetResult is not None
-        assert MentalModelRefreshResult is not None
@@ -312,49 +312,6 @@ class TestDirectiveTags:
        # Cleanup
        await memory.delete_bank(bank_id, request_context=request_context)

-    async def test_list_all_directives_without_filter(self, memory: MemoryEngine, request_context):
-        """Test that listing directives without tags returns ALL directives (both tagged and untagged)."""
-        bank_id = f"test-directive-list-all-{uuid.uuid4().hex[:8]}"
-
-        # Ensure bank exists
-        await memory.get_bank_profile(bank_id, request_context=request_context)
-
-        # Create untagged directive
-        await memory.create_directive(
-            bank_id=bank_id,
-            name="Untagged Directive",
-            content="This has no tags",
-            request_context=request_context,
-        )
-
-        # Create tagged directive
-        await memory.create_directive(
-            bank_id=bank_id,
-            name="Tagged Directive",
-            content="This has tags",
-            tags=["project-x"],
-            request_context=request_context,
-        )
-
-        # List ALL directives (no tag filter, isolation_mode defaults to False)
-        all_directives = await memory.list_directives(
-            bank_id=bank_id,
-            request_context=request_context,
-        )
-
-        # Should return BOTH tagged and untagged directives
-        assert len(all_directives) == 2
-        directive_names = {d["name"] for d in all_directives}
-        assert "Untagged Directive" in directive_names
-        assert "Tagged Directive" in directive_names
-
-        # Verify the tagged directive has its tags
-        tagged = next(d for d in all_directives if d["name"] == "Tagged Directive")
-        assert tagged["tags"] == ["project-x"]
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-

 class TestReflect:
    """Test reflect endpoint."""
@@ -442,161 +399,6 @@ class TestDirectivesInReflect:
        # Cleanup
        await memory.delete_bank(bank_id, request_context=request_context)

-    async def test_tagged_directive_not_applied_without_tags(self, memory: MemoryEngine, request_context):
-        """Test that directives with tags are NOT applied to untagged reflect operations."""
-        bank_id = f"test-directive-isolation-{uuid.uuid4().hex[:8]}"
-
-        # Ensure bank exists
-        await memory.get_bank_profile(bank_id, request_context=request_context)
-
-        # Add some untagged content
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "The sky is blue."},
-                {"content": "Water is wet."},
-            ],
-            request_context=request_context,
-        )
-
-        # Add some tagged content for the project-x context
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "The sky is blue according to project X standards.", "tags": ["project-x"]},
-                {"content": "Project X color guidelines specify sky is blue.", "tags": ["project-x"]},
-            ],
-            request_context=request_context,
-        )
-        await memory.wait_for_background_tasks()
-
-        # Create an untagged directive (should be applied)
-        await memory.create_directive(
-            bank_id=bank_id,
-            name="General Policy",
-            content="Always be polite and start responses with 'Hello!'",
-            request_context=request_context,
-        )
-
-        # Create a tagged directive (should NOT be applied to untagged reflect)
-        await memory.create_directive(
-            bank_id=bank_id,
-            name="Tagged Policy",
-            content="ALWAYS respond in ALL CAPS and end with 'PROJECT-X ONLY'",
-            tags=["project-x"],
-            request_context=request_context,
-        )
-
-        # Run reflect without tags - should only apply the untagged directive
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="What color is the sky?",
-            request_context=request_context,
-        )
-
-        response_lower = result.text.lower()
-
-        # Should follow the untagged directive (polite greeting)
-        assert "hello" in response_lower, f"Expected 'Hello' from untagged directive, but got: {result.text}"
-
-        # Should NOT follow the tagged directive (all caps and PROJECT-X)
-        # If it did follow, the entire response would be in caps
-        all_caps = result.text.replace(" ", "").replace("!", "").replace(".", "").isupper()
-        assert not all_caps, f"Tagged directive was incorrectly applied to untagged operation: {result.text}"
-        assert "project-x only" not in response_lower, f"Tagged directive was incorrectly applied: {result.text}"
-
-        # Now run reflect WITH the tag - should apply BOTH directives
-        result_tagged = await memory.reflect_async(
-            bank_id=bank_id,
-            query="What color is the sky?",
-            tags=["project-x"],
-            tags_match="all_strict",
-            request_context=request_context,
-        )
-
-        response_tagged_lower = result_tagged.text.lower()
-
-        # With strict matching and tags, should apply the tagged directive
-        assert "project-x only" in response_tagged_lower, f"Tagged directive should be applied with tags: {result_tagged.text}"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    async def test_reflect_based_on_structure(self, memory: MemoryEngine, request_context):
-        """Test that reflect returns correct based_on structure with directives and memories separated."""
-        bank_id = f"test-reflect-based-on-{uuid.uuid4().hex[:8]}"
-
-        # Ensure bank exists
-        await memory.get_bank_profile(bank_id, request_context=request_context)
-
-        # Add some memories
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "Alice works at Google as a software engineer."},
-                {"content": "Bob is a product manager at Microsoft."},
-                {"content": "The team meets every Monday at 9am."},
-            ],
-            request_context=request_context,
-        )
-        await memory.wait_for_background_tasks()
-
-        # Create a directive
-        directive = await memory.create_directive(
-            bank_id=bank_id,
-            name="Professional Tone",
-            content="Always maintain a professional and formal tone in responses.",
-            request_context=request_context,
-        )
-        directive_id = directive["id"]
-
-        # Run reflect which returns the core result
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="Who works at Google?",
-            request_context=request_context,
-        )
-
-        # Verify based_on structure exists
-        assert result.based_on is not None
-
-        # Verify directives key exists and contains our directive
-        assert "directives" in result.based_on
-        directives_list = result.based_on.get("directives", [])
-
-        # Verify directives are dicts with id, name, content (not MemoryFact objects)
-        assert len(directives_list) > 0, "Should have at least one directive"
-        directive_found = False
-        for d in directives_list:
-            assert isinstance(d, dict), f"Directive should be dict, got {type(d)}"
-            assert "id" in d, "Directive dict should have 'id'"
-            assert "name" in d, "Directive dict should have 'name'"
-            assert "content" in d, "Directive dict should have 'content'"
-            # Check if this is our directive
-            if d["id"] == directive_id:
-                directive_found = True
-                assert d["name"] == "Professional Tone"
-                assert "professional" in d["content"].lower()
-
-        assert directive_found, f"Our directive {directive_id} should be in based_on.directives"
-
-        # Verify memories (world/experience) are separate from directives
-        has_memories = "world" in result.based_on or "experience" in result.based_on
-        assert has_memories, "Should have world or experience memories"
-
-        # Verify that if mental-models key exists, it's separate from directives
-        if "mental-models" in result.based_on:
-            mental_models = result.based_on.get("mental-models", [])
-            # Verify mental models are MemoryFact objects, not dicts like directives
-            for mm in mental_models:
-                assert hasattr(mm, "fact_type"), "Mental model should be MemoryFact with fact_type"
-                assert mm.fact_type == "mental-models"
-                assert hasattr(mm, "context")
-                assert "mental model" in mm.context.lower()
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-

 class TestDirectivesPromptInjection:
    """Test that directives are properly injected into the system prompt."""
@@ -649,264 +451,3 @@ class TestDirectivesPromptInjection:
        directives_pos = prompt.find("## DIRECTIVES")
        critical_rules_pos = prompt.find("## CRITICAL RULES")
        assert directives_pos < critical_rules_pos
-
-
-class TestMentalModelRefreshTagSecurity:
-    """Test that mental model refresh respects tag-based security boundaries."""
-
-    async def test_refresh_with_tags_only_accesses_same_tagged_models(
-        self, memory: MemoryEngine, request_context
-    ):
-        """Test that refreshing a mental model with tags can only access other models with the same tags.
-
-        This is a security test to ensure that mental models with tags (e.g., user:alice)
-        cannot access mental models from other scopes (e.g., user:bob or no tags) during refresh.
-        """
-        bank_id = f"test-refresh-tags-{uuid.uuid4().hex[:8]}"
-
-        # Ensure bank exists
-        await memory.get_bank_profile(bank_id, request_context=request_context)
-
-        # Add some facts with different tags
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "Alice works on the frontend React project. Alice's favorite color is blue.", "tags": ["user:alice"]},
-                {"content": "Alice prefers working in the morning. Alice drinks coffee every day.", "tags": ["user:alice"]},
-                {"content": "Bob works on the backend API services. Bob's favorite language is Python.", "tags": ["user:bob"]},
-                {"content": "Bob prefers working at night. Bob drinks tea every day.", "tags": ["user:bob"]},
-                {"content": "The company has 100 employees and is growing fast.", "tags": []},  # No tags
-            ],
-            request_context=request_context,
-        )
-
-        # Wait for background processing
-        await memory.wait_for_background_tasks()
-
-        # Create mental model for user:alice with sensitive data
-        mm_alice = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Alice's Work Profile",
-            source_query="What does Alice work on?",
-            content="Alice is a frontend engineer specializing in React",
-            tags=["user:alice"],
-            request_context=request_context,
-        )
-
-        # Create mental model for user:bob with sensitive data
-        mm_bob = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Bob's Work Profile",
-            source_query="What does Bob work on?",
-            content="Bob is a backend engineer specializing in Python",
-            tags=["user:bob"],
-            request_context=request_context,
-        )
-
-        # Create mental model with no tags (should not be accessible from tagged models)
-        mm_untagged = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Company Info",
-            source_query="What is the company info?",
-            content="The company has 100 employees",
-            request_context=request_context,
-        )
-
-        # Create a mental model for user:alice that will be refreshed
-        mm_alice_refresh = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Alice's Summary",
-            source_query="What are all the facts about work and preferences?",  # Broad query that should match all facts
-            content="Initial content",
-            tags=["user:alice"],
-            request_context=request_context,
-        )
-
-        # Refresh Alice's mental model
-        refreshed = await memory.refresh_mental_model(
-            bank_id=bank_id,
-            mental_model_id=mm_alice_refresh["id"],
-            request_context=request_context,
-        )
-
-        # SECURITY CHECK: The refreshed content should ONLY include information from
-        # memories/models tagged with user:alice, NOT from user:bob or untagged
-        refreshed_content = refreshed["content"].lower()
-
-        # Should include Alice's content (either from facts or mental models)
-        assert "alice" in refreshed_content, \
-            "Refreshed model should access memories/models with matching tags (user:alice)"
-
-        # MUST NOT include Bob's content (security violation)
-        # Use word boundary matching to avoid false positives (e.g., "team" contains "tea")
-        import re
-        def contains_word(text: str, word: str) -> bool:
-            """Check if text contains word as a whole word (not substring)."""
-            return bool(re.search(rf'\b{re.escape(word)}\b', text, re.IGNORECASE))
-
-        assert not contains_word(refreshed_content, "bob") and \
-               not contains_word(refreshed_content, "python") and \
-               not contains_word(refreshed_content, "tea"), \
-            f"SECURITY VIOLATION: Refreshed model accessed memories/models with different tags (user:bob). Content: {refreshed['content']}"
-
-        # MUST NOT include untagged content (security violation)
-        assert "100 employees" not in refreshed_content and "growing fast" not in refreshed_content, \
-            f"SECURITY VIOLATION: Refreshed model accessed untagged memories/models. Content: {refreshed['content']}"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    async def test_consolidation_only_refreshes_matching_tagged_models(
-        self, memory: MemoryEngine, request_context
-    ):
-        """Test that consolidation only triggers refresh for mental models with matching tags.
-
-        This is a security test to ensure that when tagged memories are consolidated,
-        only mental models with overlapping tags get refreshed, not all mental models.
-        """
-        bank_id = f"test-consolidation-refresh-{uuid.uuid4().hex[:8]}"
-
-        # Ensure bank exists
-        await memory.get_bank_profile(bank_id, request_context=request_context)
-
-        # Create mental models with different tags, all with refresh_after_consolidation=true
-        mm_alice = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Alice's Model",
-            source_query="What about Alice?",
-            content="Initial Alice content",
-            tags=["user:alice"],
-            trigger={"refresh_after_consolidation": True},
-            request_context=request_context,
-        )
-
-        mm_bob = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Bob's Model",
-            source_query="What about Bob?",
-            content="Initial Bob content",
-            tags=["user:bob"],
-            trigger={"refresh_after_consolidation": True},
-            request_context=request_context,
-        )
-
-        mm_untagged = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Untagged Model",
-            source_query="What about general stuff?",
-            content="Initial untagged content",
-            trigger={"refresh_after_consolidation": True},
-            request_context=request_context,
-        )
-
-        # Record initial last_refreshed_at timestamps
-        alice_initial = mm_alice["last_refreshed_at"]
-        bob_initial = mm_bob["last_refreshed_at"]
-        untagged_initial = mm_untagged["last_refreshed_at"]
-
-        # Add memories with user:alice tags
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "Alice likes React", "tags": ["user:alice"]},
-                {"content": "Alice drinks coffee", "tags": ["user:alice"]},
-            ],
-            request_context=request_context,
-        )
-
-        # Trigger consolidation manually (this should only refresh Alice's mental model)
-        from hindsight_api.engine.consolidation.consolidator import run_consolidation_job
-
-        result = await run_consolidation_job(
-            memory_engine=memory,
-            bank_id=bank_id,
-            request_context=request_context,
-        )
-
-        # Wait for background refresh tasks to complete
-        await memory.wait_for_background_tasks()
-
-        # Check that mental models were refreshed appropriately
-        mm_alice_after = await memory.get_mental_model(
-            bank_id, mm_alice["id"], request_context=request_context
-        )
-        mm_bob_after = await memory.get_mental_model(
-            bank_id, mm_bob["id"], request_context=request_context
-        )
-        mm_untagged_after = await memory.get_mental_model(
-            bank_id, mm_untagged["id"], request_context=request_context
-        )
-
-        # SECURITY CHECK: Only Alice's mental model and untagged model should be refreshed
-        # Alice's model should be refreshed (tags match)
-        assert mm_alice_after["last_refreshed_at"] != alice_initial or mm_alice_after["content"] != mm_alice["content"], \
-            "Alice's mental model should be refreshed when user:alice memories are consolidated"
-
-        # Bob's model should NOT be refreshed (tags don't match)
-        assert mm_bob_after["last_refreshed_at"] == bob_initial, \
-            "SECURITY VIOLATION: Bob's mental model was refreshed even though user:bob memories were not consolidated"
-
-        # Untagged model should be refreshed (untagged models are always refreshed)
-        assert mm_untagged_after["last_refreshed_at"] != untagged_initial or mm_untagged_after["content"] != mm_untagged["content"], \
-            "Untagged mental model should be refreshed after any consolidation"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    async def test_refresh_mental_model_with_directives(self, memory: MemoryEngine, request_context):
-        """Test that refreshing a mental model with directives works correctly."""
-        bank_id = f"test-refresh-directives-{uuid.uuid4().hex[:8]}"
-
-        # Ensure bank exists
-        await memory.get_bank_profile(bank_id, request_context=request_context)
-
-        # Create a directive
-        directive = await memory.create_directive(
-            bank_id=bank_id,
-            name="Response Style",
-            content="Always be concise and professional",
-            request_context=request_context,
-        )
-
-        # Create a concept mental model to refresh
-        concept = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Team Info",
-            source_query="Team information summary",
-            content="Initial team information",
-            request_context=request_context,
-        )
-
-        # Add some memories
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "Alice is the team lead and handles project planning."},
-                {"content": "Bob is a senior engineer who mentors junior developers."},
-            ],
-            request_context=request_context,
-        )
-
-        # Wait for retain to complete
-        await memory.wait_for_background_tasks()
-
-        # Refresh the concept mental model (this should include directive in based_on)
-        refreshed = await memory.refresh_mental_model(
-            bank_id=bank_id,
-            mental_model_id=concept["id"],
-            request_context=request_context,
-        )
-
-        # Wait for background tasks to complete
-        await memory.wait_for_background_tasks()
-
-        # Verify the refresh completed without errors
-        assert refreshed is not None
-        assert refreshed["content"] is not None
-
-        # Get the updated mental model
-        updated = await memory.get_mental_model(bank_id, concept["id"], request_context=request_context)
-        assert updated["content"] != "Initial team information"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
@@ -358,7 +358,7 @@ class TestLLMMetrics:
        collector.record_llm_call(
            provider="gemini",
            model="gemini-pro",
-            scope="memory",
+            scope="entity_observation",
            duration=2.0,
            success=True,
        )
@@ -369,11 +369,11 @@ class TestLLMMetrics:
        assert call_args[0][0] == 1
        assert call_args[0][1]["provider"] == "gemini"
        assert call_args[0][1]["model"] == "gemini-pro"
-        assert call_args[0][1]["scope"] == "memory"
+        assert call_args[0][1]["scope"] == "entity_observation"

    def test_record_llm_call_different_scopes(self, collector):
        """Test recording LLM calls with different scopes."""
-        scopes = ["memory", "reflect", "consolidation", "answer"]
+        scopes = ["memory", "reflect", "entity_observation", "answer"]

        for scope in scopes:
            collector.llm_duration.record.reset_mock()
@@ -469,6 +469,7 @@ async def test_mixed_language_entities(memory, request_context):
            budget=Budget.MID,
            max_tokens=1000,
            fact_type=["world"],
+            include_entities=True,
            request_context=request_context,
        )

@@ -8,20 +8,9 @@ populated from the summary for backwards compatibility.
 import pytest
 from hindsight_api.engine.memory_engine import Budget
 from hindsight_api import RequestContext
-from hindsight_api.config import get_config
 from datetime import datetime, timezone


-@pytest.fixture
-def disable_observations():
-    """Disable observations for a specific test."""
-    config = get_config()
-    original_value = config.enable_observations
-    config.enable_observations = False
-    yield
-    config.enable_observations = original_value
-
-
@pytest.mark.asyncio
 async def test_entity_extraction_on_retain(memory, request_context):
    """
@@ -91,13 +80,156 @@ async def test_entity_extraction_on_retain(memory, request_context):
            await conn.execute("DELETE FROM entities WHERE bank_id = $1", bank_id)


+@pytest.mark.asyncio
+async def test_regenerate_entity_observations(memory, request_context):
+    """
+    Test explicit regeneration of summary for an entity.
+    """
+    bank_id = f"test_regen_obs_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store facts about an entity
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Sarah is a product manager who loves user research and data analysis.",
+            context="work info",
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        await memory.wait_for_background_tasks()
+
+        # Find the Sarah entity
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            entity_row = await conn.fetchrow(
+                """
+                SELECT id, canonical_name
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%sarah%'
+                LIMIT 1
+                """,
+                bank_id
+            )
+
+        if entity_row:
+            entity_id = str(entity_row['id'])
+            entity_name = entity_row['canonical_name']
+
+            # Manually regenerate summary (via observations API for backwards compat)
+            created_ids = await memory.regenerate_entity_observations(
+                bank_id=bank_id,
+                entity_id=entity_id,
+                entity_name=entity_name,
+                request_context=request_context,
+            )
+
+            print(f"\n=== Regenerated Summary ===")
+            print(f"Created {len(created_ids)} summary for {entity_name}")
+
+            # Get entity state
+            state = await memory.get_entity_state(
+                bank_id, entity_id, entity_name, request_context=request_context
+            )
+            for obs in state.observations:
+                print(f"  - {obs.text}")
+
+            # Verify summary was created
+            if len(created_ids) > 0:
+                assert len(state.observations) == 1, "Should have exactly 1 observation (the summary)"
+                print(f"Summary regenerated successfully")
+            else:
+                print(f"Note: No summary was regenerated")
+
+        else:
+            print(f"Note: No 'Sarah' entity was extracted")
+
+    finally:
+        # Cleanup
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            await conn.execute("DELETE FROM memory_units WHERE bank_id = $1", bank_id)
+            await conn.execute("DELETE FROM entities WHERE bank_id = $1", bank_id)
+
+
+@pytest.mark.asyncio
+async def test_entity_state_retrieval(memory, request_context):
+    """
+    Test retrieving entity state with facts.
+    """
+    bank_id = f"test_entity_state_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store facts
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice works at Google as a senior software engineer.",
+            context="work info",
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice loves hiking and outdoor photography.",
+            context="hobbies",
+            event_date=datetime(2024, 1, 16, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        # Find the Alice entity
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            entity_row = await conn.fetchrow(
+                """
+                SELECT id, canonical_name
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%alice%'
+                LIMIT 1
+                """,
+                bank_id
+            )
+
+        assert entity_row is not None, "Alice entity should have been extracted"
+
+        entity_id = str(entity_row['id'])
+        entity_name = entity_row['canonical_name']
+
+        # Check fact count
+        async with pool.acquire() as conn:
+            fact_count = await conn.fetchval(
+                "SELECT COUNT(*) FROM unit_entities WHERE entity_id = $1",
+                entity_row['id']
+            )
+
+        print(f"\n=== Entity State Test ===")
+        print(f"Entity: {entity_name} (id: {entity_id})")
+        print(f"Linked facts: {fact_count}")
+
+        # Get entity state
+        state = await memory.get_entity_state(
+            bank_id, entity_id, entity_name, request_context=request_context
+        )
+
+        assert state.entity_id == entity_id
+        assert state.canonical_name == entity_name
+        print(f"Entity state retrieved successfully")
+
+    finally:
+        # Cleanup
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            await conn.execute("DELETE FROM memory_units WHERE bank_id = $1", bank_id)
+            await conn.execute("DELETE FROM entities WHERE bank_id = $1", bank_id)
+
+
@pytest.mark.asyncio
 async def test_search_with_include_entities(memory, request_context):
    """
-    Test that recall accepts include_entities parameter for backwards compatibility.
+    Test that search with include_entities=True returns entity information.

-    Note: Entity observations have been deprecated. This test verifies the parameter
-    is still accepted without errors.
+    This test verifies that:
+    1. Entities are extracted after retain
+    2. Entity info is returned in recall results with include_entities=True
    """
    bank_id = f"test_search_ent_{datetime.now(timezone.utc).timestamp()}"

@@ -106,6 +238,10 @@ async def test_search_with_include_entities(memory, request_context):
        contents = [
            "Alice is a data scientist who works on recommendation systems at Netflix.",
            "Alice presented her research at the ML conference last month.",
+            "Alice is an expert in deep learning and neural networks.",
+            "Alice graduated from Stanford with a PhD in Computer Science.",
+            "Alice leads a team of 5 data scientists at Netflix.",
+            "Alice published a paper on collaborative filtering algorithms.",
        ]

        for i, content in enumerate(contents):
@@ -120,7 +256,7 @@ async def test_search_with_include_entities(memory, request_context):
        # Wait for background tasks
        await memory.wait_for_background_tasks()

-        # Search with include_entities=True (should be accepted for backwards compatibility)
+        # Search with include_entities=True
        result = await memory.recall_async(
            bank_id=bank_id,
            query="What does Alice do?",
@@ -132,9 +268,35 @@ async def test_search_with_include_entities(memory, request_context):
            request_context=request_context,
        )

-        # Verify recall works
-        assert len(result.results) > 0, "Should find some facts"
+        print(f"\n=== Search Results ===")
        print(f"Found {len(result.results)} facts")
+        for fact in result.results:
+            print(f"  - {fact.text}")
+            if fact.entities:
+                print(f"    Entities: {', '.join(fact.entities)}")
+
+        # Verify results
+        assert len(result.results) > 0, "Should find some facts"
+
+        # Check if entities are included in facts
+        facts_with_entities = [f for f in result.results if f.entities]
+        assert len(facts_with_entities) > 0, "Some facts should have entity information"
+        print(f"{len(facts_with_entities)} facts have entity information")
+
+        # Check if entity info is returned
+        if result.entities:
+            print(f"Entity info included for {len(result.entities)} entities")
+
+            # Verify Alice entity is in results
+            alice_found = False
+            for name, state in result.entities.items():
+                assert state.canonical_name == name, "Entity canonical_name should match key"
+                assert state.entity_id, "Entity should have an ID"
+                if "alice" in name.lower():
+                    alice_found = True
+                    print(f"Alice entity found: {name}")
+
+            assert alice_found, "Alice entity should be in recall results"

    finally:
        # Cleanup
@@ -145,12 +307,75 @@ async def test_search_with_include_entities(memory, request_context):


@pytest.mark.asyncio
-async def test_observation_fact_type_in_database(memory, request_context, disable_observations):
+async def test_get_entity_state(memory, request_context):
    """
-    Test that when observations are disabled, no observation records are created.
+    Test getting the full state of an entity.
+    """
+    bank_id = f"test_entity_state_{datetime.now(timezone.utc).timestamp()}"

-    When enable_observations=False, consolidation does not run and no
-    memory_units with fact_type='observation' should exist.
+    try:
+        # Store facts
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Bob is a frontend developer who specializes in React and TypeScript.",
+            context="work info",
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        await memory.wait_for_background_tasks()
+
+        # Find entity
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            entity_row = await conn.fetchrow(
+                """
+                SELECT id, canonical_name
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%bob%'
+                LIMIT 1
+                """,
+                bank_id
+            )
+
+        if entity_row:
+            entity_id = str(entity_row['id'])
+            entity_name = entity_row['canonical_name']
+
+            # Get entity state
+            state = await memory.get_entity_state(
+                bank_id=bank_id,
+                entity_id=entity_id,
+                entity_name=entity_name,
+                limit=10,
+                request_context=request_context,
+            )
+
+            print(f"\n=== Entity State for {entity_name} ===")
+            print(f"Entity ID: {state.entity_id}")
+            print(f"Canonical Name: {state.canonical_name}")
+            print(f"Observations: {len(state.observations)}")
+            for obs in state.observations:
+                print(f"  - {obs.text}")
+
+            assert state.entity_id == entity_id, "Entity ID should match"
+            assert state.canonical_name == entity_name, "Canonical name should match"
+
+    finally:
+        # Cleanup
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            await conn.execute("DELETE FROM memory_units WHERE bank_id = $1", bank_id)
+            await conn.execute("DELETE FROM entities WHERE bank_id = $1", bank_id)
+
+
+@pytest.mark.asyncio
+async def test_observation_fact_type_in_database(memory, request_context):
+    """
+    Test that observations are NOT stored as memory_units with fact_type='observation'.
+
+    NOTE: Observations are now handled via mental models, not as memory_units
+    or entity summaries.
    """
    bank_id = f"test_obs_db_{datetime.now(timezone.utc).timestamp()}"

@@ -275,88 +275,3 @@ class TestReflectUsesReflectLLMConfig:

        # Verify it's different from the retain config
        assert engine._reflect_llm_config.model != engine._retain_llm_config.model
-
-
-class TestRetryAndBackoffConfiguration:
-    """Test retry and backoff configuration options."""
-
-    def test_global_retry_backoff_config_defaults(self):
-        """Test that global retry/backoff settings have correct defaults."""
-        from hindsight_api.config import get_config
-
-        config = get_config()
-
-        # Verify global defaults
-        assert config.llm_max_retries == 10
-        assert config.llm_initial_backoff == 1.0
-        assert config.llm_max_backoff == 60.0
-
-    def test_per_operation_retry_backoff_config_from_env(self):
-        """Test that per-operation retry/backoff settings are loaded from environment."""
-        from hindsight_api.config import clear_config_cache
-
-        # Set per-operation overrides
-        os.environ["HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES"] = "3"
-        os.environ["HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF"] = "2.0"
-        os.environ["HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF"] = "120.0"
-        os.environ["HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES"] = "5"
-        os.environ["HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF"] = "1.5"
-        os.environ["HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF"] = "90.0"
-
-        try:
-            clear_config_cache()
-            from hindsight_api.config import get_config
-
-            config = get_config()
-
-            # Verify retain overrides
-            assert config.retain_llm_max_retries == 3
-            assert config.retain_llm_initial_backoff == 2.0
-            assert config.retain_llm_max_backoff == 120.0
-
-            # Verify reflect overrides
-            assert config.reflect_llm_max_retries == 5
-            assert config.reflect_llm_initial_backoff == 1.5
-            assert config.reflect_llm_max_backoff == 90.0
-
-            # Verify global defaults remain unchanged
-            assert config.llm_max_retries == 10
-            assert config.llm_initial_backoff == 1.0
-            assert config.llm_max_backoff == 60.0
-        finally:
-            # Clean up
-            os.environ.pop("HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES", None)
-            os.environ.pop("HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES", None)
-            os.environ.pop("HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF", None)
-            clear_config_cache()
-
-    def test_per_operation_retry_backoff_fallback_to_global(self):
-        """Test that per-operation settings fall back to global when not set."""
-        from hindsight_api.config import clear_config_cache, get_config
-
-        # Set only global values
-        os.environ["HINDSIGHT_API_LLM_MAX_RETRIES"] = "7"
-        os.environ["HINDSIGHT_API_LLM_INITIAL_BACKOFF"] = "3.0"
-        os.environ["HINDSIGHT_API_LLM_MAX_BACKOFF"] = "180.0"
-
-        try:
-            clear_config_cache()
-            config = get_config()
-
-            # Per-operation should be None (will fall back to global at runtime)
-            assert config.retain_llm_max_retries is None
-            assert config.retain_llm_initial_backoff is None
-            assert config.retain_llm_max_backoff is None
-
-            # Global values should be set
-            assert config.llm_max_retries == 7
-            assert config.llm_initial_backoff == 3.0
-            assert config.llm_max_backoff == 180.0
-        finally:
-            os.environ.pop("HINDSIGHT_API_LLM_MAX_RETRIES", None)
-            os.environ.pop("HINDSIGHT_API_LLM_INITIAL_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_LLM_MAX_BACKOFF", None)
-            clear_config_cache()
@@ -1,123 +0,0 @@
-"""Test provider-specific default models in config."""
-
-import os
-
-import pytest
-
-
-def test_provider_default_models():
-    """Test that each provider has a default model and it's used when model is not explicitly set."""
-    from hindsight_api.config import PROVIDER_DEFAULT_MODELS, HindsightConfig, clear_config_cache
-
-    # Save original env vars
-    original_provider = os.environ.get("HINDSIGHT_API_LLM_PROVIDER")
-    original_model = os.environ.get("HINDSIGHT_API_LLM_MODEL")
-
-    try:
-        # Test each provider has a default
-        for provider, expected_model in PROVIDER_DEFAULT_MODELS.items():
-            clear_config_cache()
-            os.environ["HINDSIGHT_API_LLM_PROVIDER"] = provider
-            # Remove explicit model setting to test default
-            if "HINDSIGHT_API_LLM_MODEL" in os.environ:
-                del os.environ["HINDSIGHT_API_LLM_MODEL"]
-
-            config = HindsightConfig.from_env()
-            assert config.llm_provider == provider, f"Provider mismatch for {provider}"
-            assert config.llm_model == expected_model, f"Expected {expected_model} for {provider}, got {config.llm_model}"
-
-    finally:
-        # Restore original env vars
-        clear_config_cache()
-        if original_provider:
-            os.environ["HINDSIGHT_API_LLM_PROVIDER"] = original_provider
-        elif "HINDSIGHT_API_LLM_PROVIDER" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_PROVIDER"]
-
-        if original_model:
-            os.environ["HINDSIGHT_API_LLM_MODEL"] = original_model
-        elif "HINDSIGHT_API_LLM_MODEL" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_MODEL"]
-
-
-def test_explicit_model_overrides_provider_default():
-    """Test that explicit model setting overrides provider default."""
-    from hindsight_api.config import HindsightConfig, clear_config_cache
-
-    original_provider = os.environ.get("HINDSIGHT_API_LLM_PROVIDER")
-    original_model = os.environ.get("HINDSIGHT_API_LLM_MODEL")
-
-    try:
-        clear_config_cache()
-        os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "anthropic"
-        os.environ["HINDSIGHT_API_LLM_MODEL"] = "claude-sonnet-4-5-20250929"
-
-        config = HindsightConfig.from_env()
-        assert config.llm_provider == "anthropic"
-        assert config.llm_model == "claude-sonnet-4-5-20250929", "Explicit model should override default"
-
-    finally:
-        clear_config_cache()
-        if original_provider:
-            os.environ["HINDSIGHT_API_LLM_PROVIDER"] = original_provider
-        elif "HINDSIGHT_API_LLM_PROVIDER" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_PROVIDER"]
-
-        if original_model:
-            os.environ["HINDSIGHT_API_LLM_MODEL"] = original_model
-        elif "HINDSIGHT_API_LLM_MODEL" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_MODEL"]
-
-
-def test_per_operation_provider_default_model():
-    """Test that per-operation providers use their own default models."""
-    from hindsight_api.config import HindsightConfig, clear_config_cache
-
-    original_provider = os.environ.get("HINDSIGHT_API_LLM_PROVIDER")
-    original_model = os.environ.get("HINDSIGHT_API_LLM_MODEL")
-    original_retain_provider = os.environ.get("HINDSIGHT_API_RETAIN_LLM_PROVIDER")
-    original_retain_model = os.environ.get("HINDSIGHT_API_RETAIN_LLM_MODEL")
-
-    try:
-        clear_config_cache()
-        os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "openai"
-        # Remove explicit model to use provider default
-        if "HINDSIGHT_API_LLM_MODEL" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_MODEL"]
-
-        # Set retain-specific provider but not model
-        os.environ["HINDSIGHT_API_RETAIN_LLM_PROVIDER"] = "anthropic"
-        if "HINDSIGHT_API_RETAIN_LLM_MODEL" in os.environ:
-            del os.environ["HINDSIGHT_API_RETAIN_LLM_MODEL"]
-
-        config = HindsightConfig.from_env()
-
-        # Global LLM should use OpenAI default
-        assert config.llm_model == "o3-mini", f"Expected o3-mini, got {config.llm_model}"
-
-        # Retain should use Anthropic default
-        assert (
-            config.retain_llm_model == "claude-haiku-4-5-20251001"
-        ), f"Expected claude-haiku-4-5-20251001, got {config.retain_llm_model}"
-
-    finally:
-        clear_config_cache()
-        if original_provider:
-            os.environ["HINDSIGHT_API_LLM_PROVIDER"] = original_provider
-        elif "HINDSIGHT_API_LLM_PROVIDER" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_PROVIDER"]
-
-        if original_model:
-            os.environ["HINDSIGHT_API_LLM_MODEL"] = original_model
-        elif "HINDSIGHT_API_LLM_MODEL" in os.environ:
-            del os.environ["HINDSIGHT_API_LLM_MODEL"]
-
-        if original_retain_provider:
-            os.environ["HINDSIGHT_API_RETAIN_LLM_PROVIDER"] = original_retain_provider
-        elif "HINDSIGHT_API_RETAIN_LLM_PROVIDER" in os.environ:
-            del os.environ["HINDSIGHT_API_RETAIN_LLM_PROVIDER"]
-
-        if original_retain_model:
-            os.environ["HINDSIGHT_API_RETAIN_LLM_MODEL"] = original_retain_model
-        elif "HINDSIGHT_API_RETAIN_LLM_MODEL" in os.environ:
-            del os.environ["HINDSIGHT_API_RETAIN_LLM_MODEL"]
@@ -14,7 +14,6 @@ from hindsight_api.engine.reflect.agent import (
    _normalize_tool_name,
    _is_done_tool,
    _clean_answer_text,
-    _clean_done_answer,
    run_reflect_agent,
 )
 from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
@@ -62,79 +61,6 @@ class TestCleanAnswerText:
        assert cleaned == "Summary of findings."


-class TestCleanDoneAnswer:
-    """Test cleanup of answer field from done() tool call that leaks structured output."""
-
-    def test_clean_answer_with_leaked_json_code_block(self):
-        """Answer with leaked JSON code block at the end should be cleaned."""
-        text = '''The user's favorite color is blue.
-
-```json
-{"observation_ids": ["obs-1", "obs-2"]}
-```'''
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "The user's favorite color is blue."
-        assert "observation_ids" not in cleaned
-
-    def test_clean_answer_with_memory_ids_code_block(self):
-        """Answer with leaked memory_ids JSON code block should be cleaned."""
-        text = '''Here is the answer.
-
-```json
-{"memory_ids": ["mem-1"]}
-```'''
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "Here is the answer."
-
-    def test_clean_answer_with_raw_json_object(self):
-        """Answer with raw JSON object containing IDs at the end should be cleaned."""
-        text = 'The answer is 42. {"observation_ids": ["obs-1"]}'
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "The answer is 42."
-
-    def test_clean_answer_with_trailing_ids_pattern(self):
-        """Answer with 'observation_ids: [...]' pattern at the end should be cleaned."""
-        text = "This is the answer.\n\nobservation_ids: [\"obs-1\", \"obs-2\"]"
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "This is the answer."
-
-    def test_clean_answer_with_memory_ids_equals(self):
-        """Answer with 'memory_ids = [...]' pattern at the end should be cleaned."""
-        text = "Answer text here.\nmemory_ids = [\"mem-1\"]"
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "Answer text here."
-
-    def test_clean_normal_answer_unchanged(self):
-        """Normal answer without leaked output should be unchanged."""
-        text = "This is a normal answer about observation strategies."
-        cleaned = _clean_done_answer(text)
-        assert cleaned == text
-
-    def test_clean_empty_answer(self):
-        """Empty answer should return empty."""
-        assert _clean_done_answer("") == ""
-
-    def test_clean_answer_with_observation_word_in_content(self):
-        """The word 'observation' in regular text should not be stripped."""
-        text = "Based on my observation, the user prefers dark mode."
-        cleaned = _clean_done_answer(text)
-        assert cleaned == text
-
-    def test_clean_answer_multiline_with_markdown(self):
-        """Answer with markdown and leaked JSON at end should clean only the leak."""
-        text = '''Summary:
- Point 1
- Point 2
-
-```json
-{"mental_model_ids": ["mm-1"]}
-```'''
-        cleaned = _clean_done_answer(text)
-        assert "Point 1" in cleaned
-        assert "Point 2" in cleaned
-        assert "mental_model_ids" not in cleaned
-
-
 class TestToolNameNormalization:
    """Test tool name normalization for various LLM output formats."""

@@ -142,15 +68,15 @@ class TestToolNameNormalization:
        """Standard tool names should pass through unchanged."""
        assert _normalize_tool_name("done") == "done"
        assert _normalize_tool_name("recall") == "recall"
+        assert _normalize_tool_name("search_reflections") == "search_reflections"
        assert _normalize_tool_name("search_mental_models") == "search_mental_models"
-        assert _normalize_tool_name("search_observations") == "search_observations"
        assert _normalize_tool_name("expand") == "expand"

    def test_normalize_functions_prefix(self):
        """Tool names with 'functions.' prefix should be normalized."""
        assert _normalize_tool_name("functions.done") == "done"
        assert _normalize_tool_name("functions.recall") == "recall"
-        assert _normalize_tool_name("functions.search_mental_models") == "search_mental_models"
+        assert _normalize_tool_name("functions.search_reflections") == "search_reflections"

    def test_normalize_call_equals_prefix(self):
        """Tool names with 'call=' prefix should be normalized."""
@@ -161,13 +87,7 @@ class TestToolNameNormalization:
        """Tool names with 'call=functions.' prefix should be normalized."""
        assert _normalize_tool_name("call=functions.done") == "done"
        assert _normalize_tool_name("call=functions.recall") == "recall"
-        assert _normalize_tool_name("call=functions.search_observations") == "search_observations"
-
-    def test_normalize_special_token_suffix(self):
-        """Tool names with malformed special tokens should be normalized."""
-        assert _normalize_tool_name("done<|channel|>commentary") == "done"
-        assert _normalize_tool_name("recall<|endoftext|>") == "recall"
-        assert _normalize_tool_name("search_observations<|im_end|>extra") == "search_observations"
+        assert _normalize_tool_name("call=functions.search_mental_models") == "search_mental_models"

    def test_is_done_tool(self):
        """Test _is_done_tool helper."""
@@ -180,14 +100,9 @@ class TestToolNameNormalization:
        assert _is_done_tool("call=done") is True
        assert _is_done_tool("call=functions.done") is True

-        # With malformed special tokens
-        assert _is_done_tool("done<|channel|>commentary") is True
-        assert _is_done_tool("done<|endoftext|>") is True
-
        # Not done
        assert _is_done_tool("functions.recall") is False
        assert _is_done_tool("call=functions.recall") is False
-        assert _is_done_tool("recall<|channel|>done") is False


 class TestReflectAgentMocked:
@@ -208,8 +123,8 @@ class TestReflectAgentMocked:
    def mock_functions(self):
        """Create mock search/recall functions."""
        return {
+            "search_reflections_fn": AsyncMock(return_value={"reflections": []}),
            "search_mental_models_fn": AsyncMock(return_value={"mental_models": []}),
-            "search_observations_fn": AsyncMock(return_value={"observations": []}),
            "recall_fn": AsyncMock(return_value={"memories": [{"id": "mem-1", "content": "test memory"}]}),
            "expand_fn": AsyncMock(return_value={"memories": []}),
        }
@@ -1,45 +0,0 @@
-"""
-Test to verify reflect operation creates proper span hierarchy.
-"""
-import pytest
-
-
-@pytest.mark.asyncio
-async def test_reflect_creates_child_spans(memory, request_context):
-    """Test that reflect operation creates child LLM spans."""
-    from datetime import datetime, timezone
-    from hindsight_api.tracing import initialize_tracing, get_span_recorder, create_span_recorder
-
-    # Initialize tracing with a mock endpoint
-    initialize_tracing(
-        service_name="test-hindsight",
-        endpoint="http://localhost:4318",
-        deployment_environment="test"
-    )
-
-    # Create span recorder
-    recorder = create_span_recorder()
-
-    bank_id = f"test-reflect-hierarchy-{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # Add some memories
-        await memory.retain_async(
-            bank_id=bank_id,
-            content="Paris is the capital of France",
-            context="Geography",
-            request_context=request_context,
-        )
-
-        # Run reflect
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="What is the capital of France?",
-            request_context=request_context,
-        )
-
-        print(f"Reflect result: {result.text[:100]}")
-        print(f"Usage: {result.usage}")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
@@ -1,4 +1,4 @@
-"""Tests for mental models (formerly reflections), observations, and learnings functionality."""
+"""Tests for reflections, mental models, and learnings functionality."""

 import uuid

@@ -21,22 +21,22 @@ async def api_client(memory):
@pytest.fixture
 def test_bank_id():
    """Provide a unique bank ID for this test run."""
-    return f"test_mental_models_{uuid.uuid4().hex[:8]}"
+    return f"test_reflections_{uuid.uuid4().hex[:8]}"


-class TestMentalModelsCRUD:
-    """Test mental models CRUD operations via memory engine."""
+class TestReflectionsCRUD:
+    """Test reflections CRUD operations via memory engine."""

    @pytest.mark.asyncio
-    async def test_create_and_get_mental_model(self, memory: MemoryEngine, request_context):
-        """Test creating and retrieving a mental model."""
-        bank_id = f"test-mental-model-{uuid.uuid4().hex[:8]}"
+    async def test_create_and_get_reflection(self, memory: MemoryEngine, request_context):
+        """Test creating and retrieving a reflection."""
+        bank_id = f"test-reflection-{uuid.uuid4().hex[:8]}"

        # Create the bank first
        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)

-        # Create a mental model
-        mental_model = await memory.create_mental_model(
+        # Create a reflection
+        reflection = await memory.create_reflection(
            bank_id=bank_id,
            name="Team Preferences",
            source_query="What are the team's communication preferences?",
@@ -45,45 +45,45 @@ class TestMentalModelsCRUD:
            request_context=request_context,
        )

-        assert mental_model["name"] == "Team Preferences"
-        assert mental_model["source_query"] == "What are the team's communication preferences?"
-        assert mental_model["content"] == "The team prefers async communication via Slack"
-        assert mental_model["tags"] == ["team"]
-        assert "id" in mental_model
+        assert reflection["name"] == "Team Preferences"
+        assert reflection["source_query"] == "What are the team's communication preferences?"
+        assert reflection["content"] == "The team prefers async communication via Slack"
+        assert reflection["tags"] == ["team"]
+        assert "id" in reflection

-        # Get the mental model
-        fetched = await memory.get_mental_model(
+        # Get the reflection
+        fetched = await memory.get_reflection(
            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
            request_context=request_context,
        )

-        assert fetched["id"] == mental_model["id"]
+        assert fetched["id"] == reflection["id"]
        assert fetched["name"] == "Team Preferences"

        # Cleanup
        await memory.delete_bank(bank_id, request_context=request_context)

    @pytest.mark.asyncio
-    async def test_list_mental_models(self, memory: MemoryEngine, request_context):
-        """Test listing mental models with filters."""
-        bank_id = f"test-mental-model-list-{uuid.uuid4().hex[:8]}"
+    async def test_list_reflections(self, memory: MemoryEngine, request_context):
+        """Test listing reflections with filters."""
+        bank_id = f"test-reflection-list-{uuid.uuid4().hex[:8]}"

        # Create the bank first
        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)

-        # Create multiple mental models
-        await memory.create_mental_model(
+        # Create multiple reflections
+        await memory.create_reflection(
            bank_id=bank_id,
-            name="Mental Model 1",
+            name="Reflection 1",
            source_query="Query 1",
            content="Content 1",
            tags=["tag1"],
            request_context=request_context,
        )
-        await memory.create_mental_model(
+        await memory.create_reflection(
            bank_id=bank_id,
-            name="Mental Model 2",
+            name="Reflection 2",
            source_query="Query 2",
            content="Content 2",
            tags=["tag2"],
@@ -91,33 +91,33 @@ class TestMentalModelsCRUD:
        )

        # List all
-        all_mental_models = await memory.list_mental_models(
+        all_reflections = await memory.list_reflections(
            bank_id=bank_id,
            request_context=request_context,
        )
-        assert len(all_mental_models) == 2
+        assert len(all_reflections) == 2

        # List with tag filter
-        tag1_mental_models = await memory.list_mental_models(
+        tag1_reflections = await memory.list_reflections(
            bank_id=bank_id,
            tags=["tag1"],
            request_context=request_context,
        )
-        assert len(tag1_mental_models) == 1
+        assert len(tag1_reflections) == 1

        # Cleanup
        await memory.delete_bank(bank_id, request_context=request_context)

    @pytest.mark.asyncio
-    async def test_update_mental_model(self, memory: MemoryEngine, request_context):
-        """Test updating a mental model."""
-        bank_id = f"test-mental-model-update-{uuid.uuid4().hex[:8]}"
+    async def test_update_reflection(self, memory: MemoryEngine, request_context):
+        """Test updating a reflection."""
+        bank_id = f"test-reflection-update-{uuid.uuid4().hex[:8]}"

        # Create the bank first
        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)

-        # Create a mental model
-        mental_model = await memory.create_mental_model(
+        # Create a reflection
+        reflection = await memory.create_reflection(
            bank_id=bank_id,
            name="Original Name",
            source_query="Original Query",
@@ -125,10 +125,10 @@ class TestMentalModelsCRUD:
            request_context=request_context,
        )

-        # Update the mental model
-        updated = await memory.update_mental_model(
+        # Update the reflection
+        updated = await memory.update_reflection(
            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
            name="Updated Name",
            content="Updated Content",
            request_context=request_context,
@@ -141,15 +141,15 @@ class TestMentalModelsCRUD:
        await memory.delete_bank(bank_id, request_context=request_context)

    @pytest.mark.asyncio
-    async def test_delete_mental_model(self, memory: MemoryEngine, request_context):
-        """Test deleting a mental model."""
-        bank_id = f"test-mental-model-delete-{uuid.uuid4().hex[:8]}"
+    async def test_delete_reflection(self, memory: MemoryEngine, request_context):
+        """Test deleting a reflection."""
+        bank_id = f"test-reflection-delete-{uuid.uuid4().hex[:8]}"

        # Create the bank first
        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)

-        # Create a mental model
-        mental_model = await memory.create_mental_model(
+        # Create a reflection
+        reflection = await memory.create_reflection(
            bank_id=bank_id,
            name="To Delete",
            source_query="Query",
@@ -157,17 +157,17 @@ class TestMentalModelsCRUD:
            request_context=request_context,
        )

-        # Delete the mental model
-        await memory.delete_mental_model(
+        # Delete the reflection
+        await memory.delete_reflection(
            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
            request_context=request_context,
        )

        # Verify deletion - should return None
-        fetched = await memory.get_mental_model(
+        fetched = await memory.get_reflection(
            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
            request_context=request_context,
        )
        assert fetched is None
@@ -175,85 +175,46 @@ class TestMentalModelsCRUD:
        # Cleanup
        await memory.delete_bank(bank_id, request_context=request_context)

-    @pytest.mark.asyncio
-    async def test_create_mental_model_with_custom_id(self, memory: MemoryEngine, request_context):
-        """Test creating a mental model with a custom ID."""
-        bank_id = f"test-mental-model-custom-id-{uuid.uuid4().hex[:8]}"

-        # Create the bank first
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
+class TestMentalModelsAPI:
+    """Test mental models API endpoints.

-        # Create a mental model with a custom ID
-        custom_id = "team-communication-preferences"
-        mental_model = await memory.create_mental_model(
-            bank_id=bank_id,
-            mental_model_id=custom_id,
-            name="Team Communication Preferences",
-            source_query="How does the team prefer to communicate?",
-            content="The team prefers async communication via Slack",
-            tags=["team", "communication"],
-            request_context=request_context,
-        )
-
-        # Verify the custom ID was used
-        assert mental_model["id"] == custom_id
-        assert mental_model["name"] == "Team Communication Preferences"
-        assert mental_model["tags"] == ["team", "communication"]
-
-        # Verify we can retrieve it with the custom ID
-        fetched = await memory.get_mental_model(
-            bank_id=bank_id,
-            mental_model_id=custom_id,
-            request_context=request_context,
-        )
-
-        assert fetched is not None
-        assert fetched["id"] == custom_id
-        assert fetched["name"] == "Team Communication Preferences"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-
-class TestObservationsAPI:
-    """Test observations API endpoints.
-
-    NOTE: Observations are now stored in memory_units with fact_type='observation'
-    and accessed via recall with fact_type=["observation"]. The old /observations
+    NOTE: Mental models are now stored in memory_units with fact_type='mental_model'
+    and accessed via recall with fact_type=["mental_model"]. The old /mental-models
    endpoint was removed. These tests are skipped.
    """

-    @pytest.mark.skip(reason="Observations endpoint removed - use recall with fact_type=['observation']")
+    @pytest.mark.skip(reason="Mental models endpoint removed - use recall with fact_type=['mental_model']")
    @pytest.mark.asyncio
-    async def test_list_observations_empty(self, api_client, test_bank_id):
-        """Test listing observations when none exist."""
+    async def test_list_mental_models_empty(self, api_client, test_bank_id):
+        """Test listing mental models when none exist."""
        pass

-    @pytest.mark.skip(reason="Observations endpoint removed - use recall with fact_type=['observation']")
+    @pytest.mark.skip(reason="Mental models endpoint removed - use recall with fact_type=['mental_model']")
    @pytest.mark.asyncio
-    async def test_get_observation_not_found(self, api_client, test_bank_id):
-        """Test getting a non-existent observation."""
+    async def test_get_mental_model_not_found(self, api_client, test_bank_id):
+        """Test getting a non-existent mental model."""
        pass


-class TestMentalModelsAPI:
-    """Test mental models API endpoints."""
+class TestReflectionsAPI:
+    """Test reflections API endpoints."""

    @pytest.mark.asyncio
-    async def test_mental_models_api_crud(self, api_client, test_bank_id):
+    async def test_reflections_api_crud(self, api_client, test_bank_id):
        """Test full CRUD cycle through API."""
        import asyncio

        # Create bank first via profile endpoint
        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")

-        # Create a mental model (async operation)
+        # Create a reflection (async operation)
        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/mental-models",
+            f"/v1/default/banks/{test_bank_id}/reflections",
            json={
-                "name": "API Test Mental Model",
+                "name": "API Test Reflection",
                "source_query": "What is the API test about?",
-                "content": "This is an API test mental model",
+                "content": "This is an API test reflection",
                "tags": ["api-test"],
            },
        )
@@ -271,72 +232,44 @@ class TestMentalModelsAPI:
                    break
            await asyncio.sleep(1)

-        # List mental models to get the created mental model
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models")
+        # List reflections to get the created reflection
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/reflections")
        assert response.status_code == 200
-        mental_models = response.json()["items"]
-        assert len(mental_models) >= 1
+        reflections = response.json()["items"]
+        assert len(reflections) >= 1

-        # Find our mental model
-        mental_model = next((m for m in mental_models if m["name"] == "API Test Mental Model"), None)
-        assert mental_model is not None, f"Mental model not found. Items: {mental_models}"
-        mental_model_id = mental_model["id"]
+        # Find our reflection
+        reflection = next((r for r in reflections if r["name"] == "API Test Reflection"), None)
+        assert reflection is not None, f"Reflection not found. Items: {reflections}"
+        reflection_id = reflection["id"]

-        # Get the mental model
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
+        # Get the reflection
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/reflections/{reflection_id}")
        assert response.status_code == 200
-        assert response.json()["name"] == "API Test Mental Model"
+        assert response.json()["name"] == "API Test Reflection"

-        # Update the mental model
+        # Update the reflection
        response = await api_client.patch(
-            f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}",
-            json={"name": "Updated API Test Mental Model"},
+            f"/v1/default/banks/{test_bank_id}/reflections/{reflection_id}",
+            json={"name": "Updated API Test Reflection"},
        )
        assert response.status_code == 200
-        assert response.json()["name"] == "Updated API Test Mental Model"
+        assert response.json()["name"] == "Updated API Test Reflection"

-        # Delete the mental model
-        response = await api_client.delete(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
+        # Delete the reflection
+        response = await api_client.delete(f"/v1/default/banks/{test_bank_id}/reflections/{reflection_id}")
        assert response.status_code == 200

        # Verify deletion
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/reflections/{reflection_id}")
        assert response.status_code == 404

        # Cleanup
        await api_client.delete(f"/v1/default/banks/{test_bank_id}")


-class TestRecallWithObservationsAndMentalModels:
-    """Test recall integration with observations and mental models."""
-
-    @pytest.mark.asyncio
-    async def test_recall_includes_observations(self, api_client, test_bank_id):
-        """Test that recall can include observations in the response."""
-        # Create bank first via profile endpoint
-        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
-
-        # Note: Observations are auto-created via consolidation, not manually
-        # This test just verifies the include parameter works
-
-        # Recall with observations included
-        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/memories/recall",
-            json={
-                "query": "What is machine learning?",
-                "include": {
-                    "observations": {"max_results": 5},
-                },
-            },
-        )
-        assert response.status_code == 200
-        result = response.json()
-
-        # Should have observations field in response (may be empty)
-        assert "observations" in result or result.get("observations") is None
-
-        # Cleanup
-        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
+class TestRecallWithMentalModelsAndReflections:
+    """Test recall integration with mental models and reflections."""

    @pytest.mark.asyncio
    async def test_recall_includes_mental_models(self, api_client, test_bank_id):
@@ -344,9 +277,37 @@ class TestRecallWithObservationsAndMentalModels:
        # Create bank first via profile endpoint
        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")

-        # Create a mental model first
+        # Note: Mental models are auto-created via consolidation, not manually
+        # This test just verifies the include parameter works
+
+        # Recall with mental models included
        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/mental-models",
+            f"/v1/default/banks/{test_bank_id}/memories/recall",
+            json={
+                "query": "What is machine learning?",
+                "include": {
+                    "mental_models": {"max_results": 5},
+                },
+            },
+        )
+        assert response.status_code == 200
+        result = response.json()
+
+        # Should have mental_models field in response (may be empty)
+        assert "mental_models" in result or result.get("mental_models") is None
+
+        # Cleanup
+        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
+
+    @pytest.mark.asyncio
+    async def test_recall_includes_reflections(self, api_client, test_bank_id):
+        """Test that recall can include reflections in the response."""
+        # Create bank first via profile endpoint
+        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
+
+        # Create a reflection first
+        response = await api_client.post(
+            f"/v1/default/banks/{test_bank_id}/reflections",
            json={
                "name": "AI Overview",
                "source_query": "What is AI?",
@@ -356,32 +317,32 @@ class TestRecallWithObservationsAndMentalModels:
        )
        assert response.status_code == 200

-        # Recall with mental models included
+        # Recall with reflections included
        response = await api_client.post(
            f"/v1/default/banks/{test_bank_id}/memories/recall",
            json={
                "query": "What is artificial intelligence?",
                "include": {
-                    "mental_models": {"max_results": 5},
+                    "reflections": {"max_results": 5},
                },
            },
        )
        assert response.status_code == 200
        result = response.json()

-        # Should have mental_models in response (may be empty if embedding not generated yet)
-        assert "mental_models" in result or result.get("mental_models") is None
+        # Should have reflections in response (may be empty if embedding not generated yet)
+        assert "reflections" in result or result.get("reflections") is None

        # Cleanup
        await api_client.delete(f"/v1/default/banks/{test_bank_id}")

    @pytest.mark.asyncio
-    async def test_recall_without_observations_by_default(self, api_client, test_bank_id):
-        """Test that recall does not include observations by default."""
+    async def test_recall_without_mental_models_by_default(self, api_client, test_bank_id):
+        """Test that recall does not include mental models by default."""
        # Create bank first via profile endpoint
        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")

-        # Recall without specifying observations
+        # Recall without specifying mental models
        response = await api_client.post(
            f"/v1/default/banks/{test_bank_id}/memories/recall",
            json={
@@ -391,97 +352,8 @@ class TestRecallWithObservationsAndMentalModels:
        assert response.status_code == 200
        result = response.json()

-        # Observations should not be in response
-        assert result.get("observations") is None
+        # Mental models should not be in response
+        assert result.get("mental_models") is None

        # Cleanup
        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-
-
-class TestReflectUsesMentalModels:
-    """Test that reflect searches and uses mental models when available."""
-
-    @pytest.mark.asyncio
-    async def test_reflect_searches_mental_models_when_available(self, memory: MemoryEngine, request_context):
-        """Test that reflect uses search_mental_models when the bank has mental models.
-
-        Given:
-        - A bank with a mental model about "team collaboration"
-
-        Expected:
-        - Reflect should call search_mental_models tool
-        - The mental model content should influence the response
-        """
-        bank_id = f"test-reflect-mm-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Create a mental model about team collaboration
-        mental_model = await memory.create_mental_model(
-            bank_id=bank_id,
-            mental_model_id=str(uuid.uuid4()),
-            name="Team Collaboration Practices",
-            source_query="How does the team collaborate?",
-            content="The team uses async communication via Slack and holds daily standups at 9am. "
-            "Code reviews are required before merging. The team values documentation and "
-            "prefers written communication for complex decisions.",
-            tags=["team"],
-            request_context=request_context,
-        )
-
-        # Run reflect with a query about team collaboration
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="How does the team work together?",
-            request_context=request_context,
-        )
-
-        # Check that mental models were searched
-        tool_calls = result.tool_trace
-        search_mm_calls = [tc for tc in tool_calls if tc.tool == "search_mental_models"]
-
-        assert len(search_mm_calls) > 0, (
-            f"Expected search_mental_models to be called when bank has mental models. "
-            f"Tool calls: {[tc.tool for tc in tool_calls]}"
-        )
-
-        # Check that the reason field is populated for debugging
-        for tc in search_mm_calls:
-            assert tc.reason is not None, "Tool call should have a reason for debugging"
-
-        # The response should mention concepts from the mental model
-        response_text = result.text.lower()
-        has_relevant_content = any(
-            keyword in response_text
-            for keyword in ["slack", "async", "standup", "code review", "documentation", "communication"]
-        )
-        assert has_relevant_content, (
-            f"Expected response to reference mental model content. Got: {result.text[:500]}"
-        )
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    @pytest.mark.asyncio
-    async def test_reflect_tool_trace_includes_reason(self, memory: MemoryEngine, request_context):
-        """Test that tool traces include the reason field for debugging."""
-        bank_id = f"test-reflect-reason-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Run reflect - it should use observations or recall
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="What is the weather like?",
-            request_context=request_context,
-        )
-
-        # All tool calls should have a reason
-        for tc in result.tool_trace:
-            if tc.tool != "done":  # done doesn't need a reason
-                assert tc.reason is not None, f"Tool {tc.tool} should have a reason for debugging"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
@@ -16,6 +16,7 @@ async def test_retain_with_chunks(memory, request_context):
    Test that retain function:
    1. Stores facts with associated chunks
    2. Recall returns chunk_id for each fact
+    3. Recall with include_entities=True also works (for compatibility)
    """
    bank_id = f"test_chunks_{datetime.now(timezone.utc).timestamp()}"
    document_id = "test_doc_123"
@@ -55,6 +56,7 @@ async def test_retain_with_chunks(memory, request_context):
            budget=Budget.LOW,
            max_tokens=500,
            fact_type=["world"],  # Search for world facts
+            include_entities=False,  # Disable entities for simpler test
            include_chunks=True,  # Enable chunks
            max_chunk_tokens=8192,
            request_context=request_context,
@@ -144,6 +146,7 @@ async def test_chunks_and_entities_follow_fact_order(memory, request_context):
            budget=Budget.MID,
            max_tokens=1000,
            fact_type=["world"],
+            include_entities=True,
            include_chunks=True,
            max_chunk_tokens=8192,
            request_context=request_context,
@@ -2079,179 +2082,3 @@ def test_recall_result_model_empty_construction():
    assert result.chunks == {}, "Should have empty chunks"

    logger.info("✓ RecallResult empty construction works correctly")
-
-
-@pytest.mark.asyncio
-async def test_custom_extraction_mode():
-    """
-    Test that custom extraction mode uses custom guidelines from env variable.
-
-    This test verifies that when HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom and
-    HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS is set, the fact extraction uses the
-    custom guidelines while keeping structural parts intact.
-    """
-    import os
-    from hindsight_api import LLMConfig
-    from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-    from hindsight_api.config import clear_config_cache
-
-    # Save original env vars
-    original_mode = os.getenv("HINDSIGHT_API_RETAIN_EXTRACTION_MODE")
-    original_instructions = os.getenv("HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS")
-
-    try:
-        # Set custom extraction mode with challenging language-specific guidelines
-        os.environ["HINDSIGHT_API_RETAIN_EXTRACTION_MODE"] = "custom"
-        os.environ["HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"] = """ONLY extract facts that are in ITALIAN language.
-
-DO NOT extract:
-❌ Facts in English
-❌ Facts in any other language besides Italian
-
-If the text contains both Italian and English content, extract ONLY the Italian facts."""
-
-        # Clear config cache to pick up new env vars
-        clear_config_cache()
-
-        # Test content with BOTH Italian (should extract) and English (should NOT extract) facts
-        # This is a much harder test than filtering greetings
-        text = """
-        The team discussed the new architecture. We will use microservices.
-
-        Il database PostgreSQL ha ridotto la latenza delle query del 60%.
-        Alice ha suggerito di usare il connection pooling per migliorare le prestazioni.
-
-        Bob mentioned that the API endpoint is ready for testing.
-        The deployment pipeline has been updated to use Kubernetes.
-
-        Marco ha completato la revisione del codice e ha approvato le modifiche.
-        Il sistema di autenticazione è stato migrato a OAuth 2.0.
-        """
-
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
-            context="team meeting notes",
-            llm_config=llm_config,
-            agent_name="TestUser"
-        )
-
-        logger.info(f"\nExtracted {len(facts)} facts with custom mode (Italian only):")
-        for i, fact in enumerate(facts):
-            logger.info(f"  {i+1}. {fact.fact}")
-
-        assert len(facts) > 0, "Should extract at least one Italian fact"
-
-        # All facts text
-        all_facts_text = " ".join([f.fact for f in facts])
-
-        # Should HAVE Italian content
-        italian_keywords = ["postgresql", "latenza", "query", "alice", "connection pooling", "prestazioni",
-                          "marco", "revisione", "codice", "autenticazione", "oauth"]
-        has_italian = any(keyword in all_facts_text.lower() for keyword in italian_keywords)
-        assert has_italian, f"Should extract Italian facts. Got: {all_facts_text}"
-
-        # Should NOT have English-only content
-        # These are facts that appear ONLY in English sections
-        english_only_keywords = ["microservices", "bob", "api endpoint", "testing", "deployment pipeline", "kubernetes"]
-
-        # Check if facts contain English-only content (this would be wrong)
-        facts_lower = all_facts_text.lower()
-        found_english_only = [kw for kw in english_only_keywords if kw in facts_lower]
-
-        if found_english_only:
-            logger.warning(f"⚠ Found English-only keywords in facts: {found_english_only}")
-            logger.warning(f"  Facts: {all_facts_text}")
-            logger.warning(f"  This may indicate the LLM is not strictly following language-specific custom guidelines")
-            # Log but don't fail - LLM behavior can vary
-        else:
-            logger.info("✓ Successfully extracted only Italian facts, ignored English facts")
-
-        # At least verify we have some Italian indicators
-        italian_indicators = ["latenza", "prestazioni", "revisione", "codice", "autenticazione"]
-        italian_count = sum(1 for ind in italian_indicators if ind in facts_lower)
-
-        assert italian_count >= 1, \
-            f"Should extract facts with Italian words. Found {italian_count} Italian indicators in: {all_facts_text}"
-
-        logger.info("✓ Custom extraction mode works with language-specific guidelines")
-        logger.info(f"✓ Extracted {len(facts)} Italian facts, found {italian_count} Italian indicators")
-
-    finally:
-        # Restore original env vars
-        if original_mode is not None:
-            os.environ["HINDSIGHT_API_RETAIN_EXTRACTION_MODE"] = original_mode
-        else:
-            os.environ.pop("HINDSIGHT_API_RETAIN_EXTRACTION_MODE", None)
-
-        if original_instructions is not None:
-            os.environ["HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"] = original_instructions
-        else:
-            os.environ.pop("HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS", None)
-
-        # Clear cache again to restore original config
-        clear_config_cache()
-
-
-@pytest.mark.asyncio
-async def test_retain_batch_with_per_item_tags_on_document(memory, request_context):
-    """
-    Test that per-item tags are correctly stored on documents.
-
-    This test verifies the fix for a bug where per-item tags in content dictionaries
-    were not being merged and passed to document tracking, causing tags to be lost
-    even though they were correctly sent through the API.
-
-    Without the fix, this test would fail because:
-    - Tags are correctly passed in the content dict
-    - Tags are correctly stored on memory_units (facts)
-    - BUT tags were NOT stored on the document record itself
-    """
-    bank_id = f"test_doc_tags_{datetime.now(timezone.utc).timestamp()}"
-    document_id = "app-state-testuser"
-
-    try:
-        # Retain content with per-item tags (simulating the TasteAI use case)
-        contents = [
-            {
-                "content": '{"username":"testuser","meals":[],"preferences":{"nickname":"testuser"}}',
-                "document_id": document_id,
-                "tags": ["user:testuser", "app-type:taste-ai"],
-            }
-        ]
-
-        result = await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=contents,
-            request_context=request_context,
-        )
-
-        assert len(result) > 0, "Should have retained content"
-        print(f"\n=== Retained content with tags ===")
-
-        # Retrieve the document
-        doc = await memory.get_document(
-            document_id=document_id,
-            bank_id=bank_id,
-            request_context=request_context,
-        )
-
-        assert doc is not None, "Document should exist"
-        assert "tags" in doc, "Document should have tags field"
-
-        # This is the critical assertion - tags should be stored on the document
-        doc_tags = doc["tags"] or []
-        print(f"Document tags: {doc_tags}")
-
-        assert "user:testuser" in doc_tags, \
-            f"Document should have 'user:testuser' tag, but got: {doc_tags}"
-        assert "app-type:taste-ai" in doc_tags, \
-            f"Document should have 'app-type:taste-ai' tag, but got: {doc_tags}"
-
-        print("✓ Per-item tags correctly stored on document")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
-        print(f"\n=== Cleaned up bank: {bank_id} ===")
@@ -22,7 +22,7 @@ TABLES = [
    "chunks",
    "async_operations",
    "directives",
-    "mental_models",
+    "reflections",
 ]

 # Files to scan for SQL queries
@@ -1,834 +0,0 @@
-"""Tests for the Supabase Tenant Extension."""
-
-import time
-from unittest.mock import AsyncMock, MagicMock, patch
-
-import httpx
-import jwt as pyjwt
-import pytest
-from jwt import PyJWK
-
-from hindsight_api.extensions.builtin.supabase_tenant import (
-    JWKS_CACHE_TTL_SECONDS,
-    JWKS_MIN_REFRESH_INTERVAL_SECONDS,
-    MIN_TOKEN_LENGTH,
-    SupabaseTenantExtension,
-)
-from hindsight_api.extensions.context import ExtensionContext
-from hindsight_api.extensions.loader import load_extension
-from hindsight_api.extensions.tenant import AuthenticationError, Tenant, TenantContext, TenantExtension
-from hindsight_api.models import RequestContext
-
-# A valid UUID for test user IDs
-VALID_UUID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
-
-# Minimal JWKS response with one RSA key
-MOCK_JWKS_RESPONSE = {
-    "keys": [
-        {
-            "kid": "test-key-1",
-            "kty": "RSA",
-            "alg": "RS256",
-            "use": "sig",
-            "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
-            "e": "AQAB",
-        }
-    ]
-}
-
-
-def _make_extension(
-    supabase_url: str = "https://test.supabase.co",
-    service_key: str | None = "test-service-key",
-    schema_prefix: str | None = None,
-) -> SupabaseTenantExtension:
-    """Helper to create a SupabaseTenantExtension with test config."""
-    config = {
-        "supabase_url": supabase_url,
-    }
-    if service_key is not None:
-        config["supabase_service_key"] = service_key
-    if schema_prefix is not None:
-        config["schema_prefix"] = schema_prefix
-    return SupabaseTenantExtension(config)
-
-
-def _make_mock_response(status_code: int = 200, json_data: dict | None = None) -> MagicMock:
-    """Helper to create a mock httpx.Response."""
-    response = MagicMock(spec=httpx.Response)
-    response.status_code = status_code
-    response.json.return_value = json_data or {}
-    response.raise_for_status = MagicMock()
-    if status_code >= 400:
-        response.raise_for_status.side_effect = httpx.HTTPStatusError("error", request=MagicMock(), response=response)
-    return response
-
-
-def _make_valid_token() -> str:
-    """Return a token that passes the MIN_TOKEN_LENGTH check."""
-    return "a" * (MIN_TOKEN_LENGTH + 10)
-
-
-def _setup_jwks_ext() -> tuple[SupabaseTenantExtension, AsyncMock]:
-    """Create an extension in JWKS mode with mocked internals."""
-    ext = _make_extension()
-    mock_client = AsyncMock(spec=httpx.AsyncClient)
-    ext._http_client = mock_client
-    ext._use_jwks = True
-    ext._jwks_keys = {"test-key-1": MagicMock(spec=PyJWK)}
-    ext._jwks_keys["test-key-1"].key = "mock-public-key"
-    ext._jwks_last_fetched = time.monotonic()
-    return ext, mock_client
-
-
-def _setup_legacy_ext() -> tuple[SupabaseTenantExtension, AsyncMock]:
-    """Create an extension in legacy mode with mocked internals."""
-    ext = _make_extension()
-    mock_client = AsyncMock(spec=httpx.AsyncClient)
-    ext._http_client = mock_client
-    ext._use_jwks = False
-    return ext, mock_client
-
-
-# ======================================================================
-# Initialization
-# ======================================================================
-
-
-class TestSupabaseTenantExtensionInit:
-    """Tests for extension initialization."""
-
-    def test_init_with_valid_config(self):
-        ext = _make_extension()
-        assert ext.supabase_url == "https://test.supabase.co"
-        assert ext.supabase_service_key == "test-service-key"
-        assert ext.schema_prefix == "user"
-        assert ext._initialized_schemas == set()
-        assert ext._http_client is None
-        assert ext._use_jwks is False
-        assert ext._jwks_keys == {}
-
-    def test_init_missing_supabase_url(self):
-        with pytest.raises(ValueError, match="HINDSIGHT_API_TENANT_SUPABASE_URL is required"):
-            SupabaseTenantExtension({})
-
-    def test_init_without_service_key(self):
-        """Service key is optional — JWKS mode doesn't require it."""
-        ext = _make_extension(service_key=None)
-        assert ext.supabase_service_key is None
-
-    def test_init_default_schema_prefix(self):
-        ext = _make_extension()
-        assert ext.schema_prefix == "user"
-
-    def test_init_custom_schema_prefix(self):
-        ext = _make_extension(schema_prefix="tenant")
-        assert ext.schema_prefix == "tenant"
-
-    def test_init_strips_trailing_slash(self):
-        ext = _make_extension(supabase_url="https://test.supabase.co/")
-        assert ext.supabase_url == "https://test.supabase.co"
-
-    def test_init_rejects_invalid_schema_prefix(self):
-        """Schema prefix with special characters should be rejected."""
-        with pytest.raises(ValueError, match="Invalid schema_prefix"):
-            _make_extension(schema_prefix='"; DROP TABLE')
-
-    def test_init_rejects_empty_schema_prefix(self):
-        with pytest.raises(ValueError, match="Invalid schema_prefix"):
-            _make_extension(schema_prefix="")
-
-    def test_init_rejects_schema_prefix_starting_with_digit(self):
-        with pytest.raises(ValueError, match="Invalid schema_prefix"):
-            _make_extension(schema_prefix="123abc")
-
-    def test_init_allows_underscore_prefix(self):
-        ext = _make_extension(schema_prefix="_internal")
-        assert ext.schema_prefix == "_internal"
-
-    def test_is_tenant_extension_subclass(self):
-        ext = _make_extension()
-        assert isinstance(ext, TenantExtension)
-
-
-# ======================================================================
-# Startup — JWKS initialization
-# ======================================================================
-
-
-class TestSupabaseTenantExtensionStartup:
-    """Tests for on_startup behavior."""
-
-    @pytest.mark.asyncio
-    async def test_on_startup_creates_http_client(self):
-        ext = _make_extension()
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-        # JWKS fetch returns keys
-        mock_client.get.return_value = _make_mock_response(200, MOCK_JWKS_RESPONSE)
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            with patch("hindsight_api.extensions.builtin.supabase_tenant.PyJWK"):
-                await ext.on_startup()
-
-        assert ext._http_client is mock_client
-
-    @pytest.mark.asyncio
-    async def test_on_startup_fetches_jwks(self):
-        ext = _make_extension()
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-        mock_client.get.return_value = _make_mock_response(200, MOCK_JWKS_RESPONSE)
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            with patch("hindsight_api.extensions.builtin.supabase_tenant.PyJWK") as mock_pyjwk:
-                mock_pyjwk.return_value = MagicMock(spec=PyJWK)
-                await ext.on_startup()
-
-        assert ext._use_jwks is True
-        # First call: JWKS fetch, second call: health check
-        assert mock_client.get.call_count == 2
-        jwks_call = mock_client.get.call_args_list[0]
-        assert jwks_call.args[0] == "https://test.supabase.co/auth/v1/.well-known/jwks.json"
-
-    @pytest.mark.asyncio
-    async def test_on_startup_falls_back_to_legacy_when_jwks_empty(self):
-        ext = _make_extension()
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-
-        # JWKS returns empty keys, health check succeeds
-        def mock_get(url, **kwargs):
-            if "jwks" in url:
-                return _make_mock_response(200, {"keys": []})
-            return _make_mock_response(200)
-
-        mock_client.get.side_effect = mock_get
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            await ext.on_startup()
-
-        assert ext._use_jwks is False
-
-    @pytest.mark.asyncio
-    async def test_on_startup_falls_back_to_legacy_when_jwks_fetch_fails(self):
-        ext = _make_extension()
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-
-        call_count = 0
-
-        def mock_get(url, **kwargs):
-            nonlocal call_count
-            call_count += 1
-            if call_count == 1:
-                # JWKS fetch fails
-                raise httpx.ConnectError("Connection refused")
-            # health check
-            return _make_mock_response(200)
-
-        mock_client.get.side_effect = mock_get
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            await ext.on_startup()
-
-        assert ext._use_jwks is False
-
-    @pytest.mark.asyncio
-    async def test_on_startup_raises_if_no_jwks_and_no_service_key(self):
-        ext = _make_extension(service_key=None)
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-        mock_client.get.return_value = _make_mock_response(200, {"keys": []})
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            with pytest.raises(ValueError, match="HINDSIGHT_API_TENANT_SUPABASE_SERVICE_KEY is required"):
-                await ext.on_startup()
-
-    @pytest.mark.asyncio
-    async def test_on_startup_health_check_with_service_key(self):
-        ext = _make_extension()
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-        mock_client.get.return_value = _make_mock_response(200, MOCK_JWKS_RESPONSE)
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            with patch("hindsight_api.extensions.builtin.supabase_tenant.PyJWK"):
-                await ext.on_startup()
-
-        # Second call should be health check
-        health_call = mock_client.get.call_args_list[1]
-        assert health_call.args[0] == "https://test.supabase.co/auth/v1/health"
-        assert health_call.kwargs["headers"] == {"apikey": "test-service-key"}
-
-    @pytest.mark.asyncio
-    async def test_on_startup_skips_health_check_without_service_key(self):
-        ext = _make_extension(service_key=None)
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-        mock_client.get.return_value = _make_mock_response(200, MOCK_JWKS_RESPONSE)
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.httpx.AsyncClient", return_value=mock_client):
-            with patch("hindsight_api.extensions.builtin.supabase_tenant.PyJWK"):
-                await ext.on_startup()
-
-        # Only one call: JWKS fetch, no health check
-        assert mock_client.get.call_count == 1
-
-
-# ======================================================================
-# JWKS cache management
-# ======================================================================
-
-
-class TestJWKSCacheManagement:
-    """Tests for JWKS key fetching, caching, and rotation handling."""
-
-    @pytest.mark.asyncio
-    async def test_get_signing_key_from_cache(self):
-        ext, _ = _setup_jwks_ext()
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header:
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            key = await ext._get_signing_key("fake-token")
-
-        assert key is ext._jwks_keys["test-key-1"]
-
-    @pytest.mark.asyncio
-    async def test_get_signing_key_refreshes_stale_cache(self):
-        ext, mock_client = _setup_jwks_ext()
-        # Make cache expired
-        ext._jwks_last_fetched = time.monotonic() - JWKS_CACHE_TTL_SECONDS - 1
-
-        new_key = MagicMock(spec=PyJWK)
-        mock_client.get.return_value = _make_mock_response(200, MOCK_JWKS_RESPONSE)
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.PyJWK", return_value=new_key),
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            key = await ext._get_signing_key("fake-token")
-
-        assert key is new_key
-        mock_client.get.assert_called_once()
-
-    @pytest.mark.asyncio
-    async def test_get_signing_key_handles_key_rotation(self):
-        """When kid not in cache and cache is old enough, refresh once for key rotation."""
-        ext, mock_client = _setup_jwks_ext()
-        # Make cache just old enough to allow a refresh
-        ext._jwks_last_fetched = time.monotonic() - JWKS_MIN_REFRESH_INTERVAL_SECONDS - 1
-
-        rotated_key = MagicMock(spec=PyJWK)
-        mock_client.get.return_value = _make_mock_response(200, MOCK_JWKS_RESPONSE)
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.PyJWK", return_value=rotated_key),
-        ):
-            mock_header.return_value = {"kid": "rotated-key-99", "alg": "RS256"}
-            # The refreshed JWKS won't have "rotated-key-99" either, so this should raise
-            with pytest.raises(AuthenticationError, match="Unable to find signing key"):
-                await ext._get_signing_key("fake-token")
-
-        # Should have attempted one refresh
-        mock_client.get.assert_called_once()
-
-    @pytest.mark.asyncio
-    async def test_get_signing_key_missing_kid_header(self):
-        ext, _ = _setup_jwks_ext()
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header:
-            mock_header.return_value = {"alg": "RS256"}  # no kid
-            with pytest.raises(AuthenticationError, match="Token missing key ID"):
-                await ext._get_signing_key("fake-token")
-
-    @pytest.mark.asyncio
-    async def test_get_signing_key_refresh_network_error(self):
-        """If JWKS refresh fails during key rotation, error should propagate."""
-        ext, mock_client = _setup_jwks_ext()
-        ext._jwks_last_fetched = time.monotonic() - JWKS_MIN_REFRESH_INTERVAL_SECONDS - 1
-
-        mock_client.get.side_effect = httpx.ConnectError("Connection refused")
-
-        with patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header:
-            mock_header.return_value = {"kid": "unknown-key", "alg": "RS256"}
-            with pytest.raises(Exception):
-                await ext._get_signing_key("fake-token")
-
-
-# ======================================================================
-# Authentication — JWKS mode
-# ======================================================================
-
-
-class TestAuthenticateJWKS:
-    """Tests for JWKS-based JWT verification."""
-
-    @pytest.mark.asyncio
-    async def test_authenticate_valid_token(self):
-        ext, _ = _setup_jwks_ext()
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": VALID_UUID, "aud": "authenticated"}
-
-            result = await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        assert isinstance(result, TenantContext)
-        expected_schema = "user_" + VALID_UUID.replace("-", "_")
-        assert result.schema_name == expected_schema
-
-    @pytest.mark.asyncio
-    async def test_authenticate_custom_prefix(self):
-        ext, _ = _setup_jwks_ext()
-        ext.schema_prefix = "org"
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": VALID_UUID}
-
-            result = await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        assert result.schema_name.startswith("org_")
-
-    @pytest.mark.asyncio
-    async def test_authenticate_expired_token(self):
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch(
-                "hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode",
-                side_effect=pyjwt.ExpiredSignatureError(),
-            ),
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-
-            with pytest.raises(AuthenticationError, match="Token has expired"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_invalid_audience(self):
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch(
-                "hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode",
-                side_effect=pyjwt.InvalidAudienceError(),
-            ),
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-
-            with pytest.raises(AuthenticationError, match="Invalid token audience"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_invalid_issuer(self):
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch(
-                "hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode",
-                side_effect=pyjwt.InvalidIssuerError(),
-            ),
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-
-            with pytest.raises(AuthenticationError, match="Invalid token issuer"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_decode_error(self):
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch(
-                "hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode",
-                side_effect=pyjwt.DecodeError(),
-            ),
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-
-            with pytest.raises(AuthenticationError, match="Invalid token"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_missing_sub_claim(self):
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"email": "[email protected]"}  # no sub
-
-            with pytest.raises(AuthenticationError, match="missing subject"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_empty_sub_claim(self):
-        """Empty string sub claim should be treated as missing."""
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": ""}
-
-            with pytest.raises(AuthenticationError, match="missing subject"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_generic_exception(self):
-        """Unexpected exceptions during decode should be caught and wrapped."""
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch(
-                "hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode",
-                side_effect=RuntimeError("unexpected internal error"),
-            ),
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-
-            with pytest.raises(AuthenticationError, match="Token verification failed"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-
-# ======================================================================
-# Authentication — Legacy mode
-# ======================================================================
-
-
-class TestAuthenticateLegacy:
-    """Tests for legacy /auth/v1/user endpoint verification."""
-
-    @pytest.mark.asyncio
-    async def test_authenticate_valid_token(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.return_value = _make_mock_response(200, {"id": VALID_UUID})
-
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        result = await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        assert isinstance(result, TenantContext)
-        expected_schema = "user_" + VALID_UUID.replace("-", "_")
-        assert result.schema_name == expected_schema
-
-    @pytest.mark.asyncio
-    async def test_authenticate_calls_user_endpoint(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.return_value = _make_mock_response(200, {"id": VALID_UUID})
-
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        token = _make_valid_token()
-        await ext.authenticate(RequestContext(api_key=token))
-
-        mock_client.get.assert_called_once_with(
-            "https://test.supabase.co/auth/v1/user",
-            headers={
-                "Authorization": f"Bearer {token}",
-                "apikey": "test-service-key",
-            },
-        )
-
-    @pytest.mark.asyncio
-    async def test_authenticate_expired_token_401(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.return_value = _make_mock_response(401)
-
-        with pytest.raises(AuthenticationError, match="Invalid or expired token"):
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_supabase_error_500(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.return_value = _make_mock_response(500)
-
-        with pytest.raises(AuthenticationError, match="Authentication failed: 500"):
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_no_user_id(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.return_value = _make_mock_response(200, {"email": "[email protected]"})
-
-        with pytest.raises(AuthenticationError, match="no user ID found"):
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_timeout(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.side_effect = httpx.TimeoutException("Request timed out")
-
-        with pytest.raises(AuthenticationError, match="Authentication timeout"):
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_connection_error(self):
-        ext, mock_client = _setup_legacy_ext()
-        mock_client.get.side_effect = httpx.ConnectError("Connection refused")
-
-        with pytest.raises(AuthenticationError, match="Connection error"):
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-
-# ======================================================================
-# Authentication — common (both modes)
-# ======================================================================
-
-
-class TestAuthenticateCommon:
-    """Tests that apply regardless of verification mode."""
-
-    @pytest.mark.asyncio
-    async def test_authenticate_missing_token(self):
-        ext, _ = _setup_jwks_ext()
-
-        with pytest.raises(AuthenticationError, match="Missing Authorization header"):
-            await ext.authenticate(RequestContext(api_key=None))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_empty_token(self):
-        ext, _ = _setup_jwks_ext()
-
-        with pytest.raises(AuthenticationError, match="Missing Authorization header"):
-            await ext.authenticate(RequestContext(api_key=""))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_short_token(self):
-        ext, _ = _setup_jwks_ext()
-
-        with pytest.raises(AuthenticationError, match="Invalid token format"):
-            await ext.authenticate(RequestContext(api_key="short"))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_not_initialized(self):
-        ext = _make_extension()
-        # _http_client is None by default
-
-        with pytest.raises(AuthenticationError, match="Extension not initialized"):
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_rejects_non_uuid_user_id(self):
-        """User IDs that aren't valid UUIDs should be rejected for schema safety."""
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": "not-a-uuid"}
-
-            with pytest.raises(AuthenticationError, match="Invalid user ID format"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-    @pytest.mark.asyncio
-    async def test_authenticate_rejects_malicious_user_id(self):
-        """User IDs with SQL injection attempts should be rejected."""
-        ext, _ = _setup_jwks_ext()
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": "'; DROP TABLE users;--"}
-
-            with pytest.raises(AuthenticationError, match="Invalid user ID format"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-
-# ======================================================================
-# Schema management
-# ======================================================================
-
-
-class TestSupabaseTenantExtensionSchemaManagement:
-    """Tests for schema initialization and caching."""
-
-    @pytest.mark.asyncio
-    async def test_schema_initialized_on_first_access(self):
-        ext, _ = _setup_jwks_ext()
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": VALID_UUID}
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        expected_schema = "user_" + VALID_UUID.replace("-", "_")
-        mock_context.run_migration.assert_called_once_with(expected_schema)
-        assert expected_schema in ext._initialized_schemas
-
-    @pytest.mark.asyncio
-    async def test_schema_cached_on_second_access(self):
-        ext, _ = _setup_jwks_ext()
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": VALID_UUID}
-
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        # run_migration should only be called once
-        expected_schema = "user_" + VALID_UUID.replace("-", "_")
-        mock_context.run_migration.assert_called_once_with(expected_schema)
-
-    @pytest.mark.asyncio
-    async def test_schema_init_failure(self):
-        ext, _ = _setup_jwks_ext()
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock(side_effect=RuntimeError("Migration failed"))
-        ext._context = mock_context
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": VALID_UUID}
-
-            with pytest.raises(AuthenticationError, match="Failed to initialize tenant"):
-                await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        # Schema should NOT be cached on failure
-        expected_schema = "user_" + VALID_UUID.replace("-", "_")
-        assert expected_schema not in ext._initialized_schemas
-
-
-# ======================================================================
-# List tenants
-# ======================================================================
-
-
-class TestSupabaseTenantExtensionListTenants:
-    """Tests for list_tenants behavior."""
-
-    @pytest.mark.asyncio
-    async def test_list_tenants_empty(self):
-        ext = _make_extension()
-        tenants = await ext.list_tenants()
-        assert tenants == []
-
-    @pytest.mark.asyncio
-    async def test_list_tenants_after_auth(self):
-        ext, _ = _setup_jwks_ext()
-        mock_context = AsyncMock(spec=ExtensionContext)
-        mock_context.run_migration = AsyncMock()
-        ext._context = mock_context
-
-        with (
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.get_unverified_header") as mock_header,
-            patch("hindsight_api.extensions.builtin.supabase_tenant.pyjwt.decode") as mock_decode,
-        ):
-            mock_header.return_value = {"kid": "test-key-1", "alg": "RS256"}
-            mock_decode.return_value = {"sub": VALID_UUID}
-            await ext.authenticate(RequestContext(api_key=_make_valid_token()))
-
-        tenants = await ext.list_tenants()
-        assert len(tenants) == 1
-        assert isinstance(tenants[0], Tenant)
-        expected_schema = "user_" + VALID_UUID.replace("-", "_")
-        assert tenants[0].schema == expected_schema
-
-
-# ======================================================================
-# Shutdown
-# ======================================================================
-
-
-class TestSupabaseTenantExtensionShutdown:
-    """Tests for on_shutdown behavior."""
-
-    @pytest.mark.asyncio
-    async def test_on_shutdown_closes_client(self):
-        ext = _make_extension()
-        mock_client = AsyncMock(spec=httpx.AsyncClient)
-        ext._http_client = mock_client
-
-        await ext.on_shutdown()
-
-        mock_client.aclose.assert_called_once()
-        assert ext._http_client is None
-
-    @pytest.mark.asyncio
-    async def test_on_shutdown_no_client(self):
-        ext = _make_extension()
-        # _http_client is None by default — should not raise
-        await ext.on_shutdown()
-
-
-# ======================================================================
-# Extension loader integration
-# ======================================================================
-
-
-class TestSupabaseTenantExtensionLoader:
-    """Tests for loading via the extension loader."""
-
-    def test_load_via_extension_loader(self, monkeypatch):
-        monkeypatch.setenv(
-            "HINDSIGHT_API_TENANT_EXTENSION",
-            "hindsight_api.extensions.builtin.supabase_tenant:SupabaseTenantExtension",
-        )
-        monkeypatch.setenv("HINDSIGHT_API_TENANT_SUPABASE_URL", "https://test.supabase.co")
-        monkeypatch.setenv("HINDSIGHT_API_TENANT_SUPABASE_SERVICE_KEY", "test-key")
-        monkeypatch.setenv("HINDSIGHT_API_TENANT_SCHEMA_PREFIX", "custom")
-
-        ext = load_extension("TENANT", TenantExtension)
-
-        assert ext is not None
-        assert isinstance(ext, SupabaseTenantExtension)
-        assert ext.supabase_url == "https://test.supabase.co"
-        assert ext.supabase_service_key == "test-key"
-        assert ext.schema_prefix == "custom"
-
-    def test_load_without_service_key(self, monkeypatch):
-        """Extension should load without service key — JWKS mode doesn't need it."""
-        monkeypatch.setenv(
-            "HINDSIGHT_API_TENANT_EXTENSION",
-            "hindsight_api.extensions.builtin.supabase_tenant:SupabaseTenantExtension",
-        )
-        monkeypatch.setenv("HINDSIGHT_API_TENANT_SUPABASE_URL", "https://test.supabase.co")
-        monkeypatch.delenv("HINDSIGHT_API_TENANT_SUPABASE_SERVICE_KEY", raising=False)
-
-        ext = load_extension("TENANT", TenantExtension)
-
-        assert ext is not None
-        assert isinstance(ext, SupabaseTenantExtension)
-        assert ext.supabase_service_key is None
--- a/Show More
+++ b/Show More