misc: add mcp integration tests and increase test coverage

2026-01-05 11:16:41 +01:00 · 2026-01-05 11:00:19 +01:00 · 2026-01-05 10:43:52 +01:00
324 changed files with 17197 additions and 56648 deletions
@@ -1,71 +0,0 @@
-name: Bug Report
-description: Report a bug or unexpected behavior
-labels: ["bug", "triage"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for taking the time to report a bug! Please fill out the sections below.
-
-  - type: textarea
-    id: description
-    attributes:
-      label: Bug Description
-      description: A clear and concise description of the bug
-      placeholder: What happened?
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: Steps to Reproduce
-      description: Steps to reproduce the behavior
-      placeholder: |
-        1. Configure '...'
-        2. Call '...'
-        3. See error
-    validations:
-      required: true
-
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected Behavior
-      description: What did you expect to happen?
-    validations:
-      required: true
-
-  - type: textarea
-    id: actual
-    attributes:
-      label: Actual Behavior
-      description: What actually happened?
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: Version
-      description: What version are you using?
-      placeholder: e.g., 0.1.0 or commit hash
-    validations:
-      required: false
-
-  - type: dropdown
-    id: llm-provider
-    attributes:
-      label: LLM Provider
-      description: Which LLM provider are you using?
-      options:
-        - OpenAI
-        - Anthropic
-        - Gemini
-        - Groq
-        - Ollama
-        - LM Studio
-        - Other
-    validations:
-      required: false
-
@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: Questions & Help
-    url: https://github.com/vectorize-io/hindsight/discussions/categories/q-a
-    about: Please ask questions and get help in Discussions instead of opening an issue.
-  - name: Ideas & Feedback
-    url: https://github.com/vectorize-io/hindsight/discussions/categories/ideas
-    about: Share ideas or give feedback in Discussions.
@@ -1,82 +0,0 @@
-name: Feature Request
-description: Suggest a new feature or enhancement
-labels: ["enhancement", "triage"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for suggesting a feature! Please describe what you'd like to see added.
-
-  - type: textarea
-    id: use-case
-    attributes:
-      label: Use Case
-      description: Describe your specific use case. What are you building? What's your goal?
-      placeholder: |
-        I'm building an AI agent that needs to...
-        My application handles...
-    validations:
-      required: true
-
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem Statement
-      description: What problem are you facing? What's missing or difficult today?
-      placeholder: Currently I have to... which causes...
-    validations:
-      required: true
-
-  - type: textarea
-    id: benefit
-    attributes:
-      label: How This Feature Would Help
-      description: Explain how this feature would improve your workflow or solve your problem
-      placeholder: With this feature, I would be able to...
-    validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: Proposed Solution
-      description: Describe your ideal solution (optional - we may have ideas too!)
-      placeholder: It would be great if Hindsight could...
-    validations:
-      required: false
-
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives Considered
-      description: Have you considered any alternative solutions or workarounds?
-    validations:
-      required: false
-
-  - type: dropdown
-    id: priority
-    attributes:
-      label: Priority
-      description: How important is this feature to you?
-      options:
-        - Nice to have
-        - Important - affects my workflow
-        - Critical - blocking my use case
-    validations:
-      required: true
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: Additional Context
-      description: Any other context, mockups, or examples?
-    validations:
-      required: false
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: Checklist
-      options:
-        - label: I would be willing to contribute this feature
-          required: false
@@ -153,15 +153,8 @@ jobs:
    - name: Build docs
      run: npm run build --workspace=hindsight-docs

-  test-rust-cli:
+  build-rust-cli:
    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_API_URL: http://localhost:8888
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

    steps:
    - uses: actions/checkout@v4
@@ -178,10 +171,6 @@ jobs:
          hindsight-cli/target
        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

-    - name: Run unit tests
-      working-directory: hindsight-cli
-      run: cargo test
-
    - name: Build CLI
      working-directory: hindsight-cli
      run: cargo build --release
@@ -193,6 +182,29 @@ jobs:
        path: hindsight-cli/target/release/hindsight
        retention-days: 1

+  test-rust-cli:
+    runs-on: ubuntu-latest
+    needs: build-rust-cli
+    env:
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_API_URL: http://localhost:8888
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Download CLI artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: hindsight-cli
+        path: /tmp/cli
+
+    - name: Make CLI executable
+      run: chmod +x /tmp/cli/hindsight
+
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -210,7 +222,7 @@ jobs:

    - name: Install API dependencies
      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+      run: uv sync --no-install-project --index-strategy unsafe-best-match

    - name: Create .env file
      run: |
@@ -239,7 +251,7 @@ jobs:

    - name: Run CLI smoke test
      run: |
-        HINDSIGHT_CLI=hindsight-cli/target/release/hindsight ./hindsight-cli/smoke-test.sh
+        HINDSIGHT_CLI=/tmp/cli/hindsight ./hindsight-cli/smoke-test.sh

    - name: Show API server logs
      if: always()
@@ -313,8 +325,6 @@ jobs:
      GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-      COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
-      HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -340,7 +350,7 @@ jobs:

    - name: Install dependencies
      working-directory: ./hindsight-api
-      run: uv sync --frozen --extra test --no-install-project --index-strategy unsafe-best-match
+      run: uv sync --extra test --no-install-project --index-strategy unsafe-best-match

    - name: Cache HuggingFace models
      uses: actions/cache@v4
@@ -401,11 +411,11 @@ jobs:

    - name: Install client test dependencies
      working-directory: ./hindsight-clients/python
-      run: uv sync --frozen --extra test --index-strategy unsafe-best-match
+      run: uv sync --extra test --index-strategy unsafe-best-match

    - name: Install API dependencies
      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+      run: uv sync --no-install-project --index-strategy unsafe-best-match

    - name: Create .env file
      run: |
@@ -478,7 +488,7 @@ jobs:

    - name: Install API dependencies
      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+      run: uv sync --no-install-project --index-strategy unsafe-best-match

    - name: Install TypeScript client dependencies
      working-directory: ./hindsight-clients/typescript
@@ -566,7 +576,7 @@ jobs:

    - name: Install API dependencies
      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+      run: uv sync --no-install-project --index-strategy unsafe-best-match

    - name: Create .env file
      run: |
@@ -633,11 +643,11 @@ jobs:

    - name: Install API dependencies
      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+      run: uv sync --no-install-project --index-strategy unsafe-best-match

    - name: Install integration test dependencies
      working-directory: ./hindsight-integration-tests
-      run: uv sync --frozen
+      run: uv sync

    - name: Cache HuggingFace models
      uses: actions/cache@v4
@@ -717,7 +727,7 @@ jobs:

    - name: Install dependencies
      working-directory: ./hindsight-integrations/litellm
-      run: uv sync --frozen --extra dev
+      run: uv sync --extra dev

    - name: Run tests
      working-directory: ./hindsight-integrations/litellm
@@ -748,7 +758,7 @@ jobs:

    - name: Install dependencies
      working-directory: ./hindsight-embed
-      run: uv sync --frozen --index-strategy unsafe-best-match
+      run: uv sync --index-strategy unsafe-best-match

    - name: Cache HuggingFace models
      uses: actions/cache@v4
@@ -765,7 +775,7 @@ jobs:

  test-doc-examples:
    runs-on: ubuntu-latest
-    needs: test-rust-cli
+    needs: build-rust-cli
    env:
      HINDSIGHT_API_LLM_PROVIDER: groq
      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
@@ -808,11 +818,11 @@ jobs:
      working-directory: ./hindsight-api
      run: |
        uv build
-        uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+        uv sync --no-install-project --index-strategy unsafe-best-match

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

    - name: Install TypeScript client
      run: |
@@ -873,76 +883,4 @@ jobs:
      if: always()
      run: |
        echo "=== API Server Logs ==="
-        cat /tmp/api-server.log || echo "No API server log found"
-
-  verify-generated-files:
-    runs-on: ubuntu-latest
-    env:
-      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
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '20'
-        cache: 'npm'
-        cache-dependency-path: package-lock.json
-
-    - name: Install Rust
-      uses: dtolnay/rust-toolchain@stable
-
-    - name: Cache cargo
-      uses: actions/cache@v4
-      with:
-        path: |
-          ~/.cargo/registry
-          ~/.cargo/git
-        key: ${{ runner.os }}-cargo-gen-${{ hashFiles('**/Cargo.lock') }}
-
-    - name: Install Node dependencies
-      run: npm ci
-
-    - name: Install Python dependencies
-      run: |
-        cd hindsight-dev && uv sync --frozen --index-strategy unsafe-best-match
-        cd ../hindsight-api && uv sync --frozen --index-strategy unsafe-best-match
-        cd ../hindsight-embed && uv sync --frozen --index-strategy unsafe-best-match
-
-    - name: Run generate-openapi
-      run: ./scripts/generate-openapi.sh
-
-    - name: Run generate-clients
-      run: ./scripts/generate-clients.sh
-
-    - name: Run lint
-      run: ./scripts/hooks/lint.sh
-
-    - name: Verify no uncommitted changes
-      run: |
-        if [ -n "$(git status --porcelain)" ]; then
-          echo "❌ Error: Generated files are out of sync with committed files."
-          echo ""
-          echo "The following files have changed after running generation scripts:"
-          git status --porcelain
-          echo ""
-          echo "Please run the following commands locally and commit the changes:"
-          echo "  ./scripts/generate-openapi.sh"
-          echo "  ./scripts/generate-clients.sh"
-          echo "  ./scripts/hooks/lint.sh"
-          echo ""
-          git diff --stat
-          exit 1
-        fi
-        echo "✓ All generated files are up to date"
+        cat /tmp/api-server.log || echo "No API server log found"
@@ -5,8 +5,7 @@ build/
 dist/
 wheels/
 *.egg-info
-.mcp.json
-.osgrep
+
 # Virtual environments
 .venv

@@ -27,10 +26,6 @@ docker-compose.override.yml
 # NLTK data (will be downloaded automatically)
 nltk_data/

-# Monitoring stack (Prometheus/Grafana binaries and data)
-.monitoring/
-.pgbouncer/
-
 # Large benchmark datasets (will be downloaded automatically)
 **/longmemeval_s_cleaned.json

@@ -46,8 +41,4 @@ hindsight-docs/static/llms-full.txt
 hindsight-dev/benchmarks/locomo/results/
 hindsight-dev/benchmarks/longmemeval/results/
 hindsight-cli/target
-hindsight-clients/rust/target
-.claude
-whats-next.md
-TASK.md
-CHANGELOG.md
+hindsight-clients/rust/target
@@ -1,3 +1,153 @@
 # AGENTS.md

-See [CLAUDE.md](./CLAUDE.md) for project documentation and coding conventions.
+This document captures architectural decisions and coding conventions for the Hindsight project.
+
+## Documentation
+
+- **Main documentation**: [hindsight-docs/docs/developer/](./hindsight-docs/docs/developer/)
+- **Use case patterns**: [hindsight-docs/docs/cookbook/](./hindsight-docs/docs/cookbook/)
+- **API reference**: Auto-generated from OpenAPI spec
+
+## Project Structure
+
+```
+hindsight/              # Python package for embedded usage
+hindsight-api/          # FastAPI server (core memory engine)
+hindsight-cli/          # Rust CLI client
+hindsight-embed/        # Embedded CLI (no server needed)
+hindsight-control-plane/ # Next.js admin UI
+hindsight-docs/         # Docusaurus documentation site
+hindsight-dev/          # Development tools and benchmarks
+hindsight-integrations/ # Framework integrations (LangChain, etc.)
+hindsight-clients/      # Generated API clients (Python, TypeScript, Rust)
+```
+
+## Core Concepts
+
+### Memory Banks
+- Each bank is an isolated memory store (like a "brain" for one user/agent)
+- Banks contain: memory units (facts), entities, documents, entity links
+- Banks have a **disposition** (personality traits) and **background** (context)
+- Bank isolation is strict - no cross-bank data leakage
+
+### Memory Types
+- **World facts**: General knowledge ("The sky is blue")
+- **Experience facts**: Personal experiences ("I visited Paris in 2023")
+- **Opinion facts**: Beliefs with confidence scores ("Paris is beautiful" - 0.9 confidence)
+
+### Operations
+- **Retain**: Store new memories (extracts facts, entities, relationships)
+- **Recall**: Retrieve memories (semantic, BM25, graph, temporal search)
+- **Reflect**: Deep analysis to form new insights/opinions
+
+## API Design Decisions
+
+### Single Bank Per Request
+- All API endpoints (`recall`, `reflect`, `retain`) operate on a single bank
+- Multi-bank queries are the **client/agent's responsibility** to orchestrate
+- This keeps the API simple and the isolation model clear
+
+### Disposition Traits (3-trait system)
+- **Skepticism** (1-5): How skeptical vs trusting when forming opinions
+- **Literalism** (1-5): How literally to interpret information
+- **Empathy** (1-5): How much to consider emotional context
+- These influence the `reflect` operation, not `recall`
+- Background info also only affects `reflect` (opinion formation)
+
+## Multi-Bank Architecture Patterns
+
+See [hindsight-docs/docs/cookbook/](./hindsight-docs/docs/cookbook/) for detailed guides:
+
+- **Per-User Memory**: One bank per user, simplest pattern
+- **Support Agent + Shared Knowledge**: User bank + shared docs bank, client orchestrates
+
+## Developer Guide
+
+### Running the API Server
+
+```bash
+# From project root
+./scripts/dev/start-api.sh
+
+# With options
+./scripts/dev/start-api.sh --reload --port 8888 --log-level debug
+```
+
+### Running Tests
+
+```bash
+# API tests
+cd hindsight-api
+uv run pytest tests/
+
+# Specific test
+uv run pytest tests/test_http_api_integration.py -v
+```
+
+### Generating OpenAPI Spec
+
+After changing API endpoints, regenerate the OpenAPI spec and docs:
+
+```bash
+./scripts/generate-openapi.sh
+```
+
+This will:
+1. Generate `openapi.json` at project root
+2. Copy to `hindsight-docs/openapi.json`
+3. Regenerate API reference documentation
+
+### Generating API Clients
+
+After updating the OpenAPI spec, regenerate all clients:
+
+```bash
+./scripts/generate-clients.sh
+```
+
+This generates:
+- **Rust client**: `hindsight-clients/rust/` (via progenitor in build.rs)
+- **Python client**: `hindsight-clients/python/` (via openapi-generator Docker)
+- **TypeScript client**: `hindsight-clients/typescript/` (via @hey-api/openapi-ts)
+
+Note: The maintained wrapper `hindsight_client.py` and `README.md` are preserved during regeneration.
+
+### Running the Documentation Site
+
+```bash
+./scripts/dev/start-docs.sh
+```
+
+### Running the Control Plane
+
+```bash
+./scripts/dev/start-control-plane.sh
+```
+
+## Code Style
+
+### Python (hindsight-api)
+- Use `uv` for package management
+- Async throughout (asyncpg, async FastAPI endpoints)
+- Pydantic models for request/response validation
+- No py files at project root - maintain clean directory structure
+
+### TypeScript (control-plane, clients)
+- Next.js with App Router for control plane
+- Tailwind CSS with shadcn/ui components
+
+### Rust (CLI)
+- Async with tokio
+- reqwest for HTTP client
+- progenitor for API client generation
+
+## Database
+
+- PostgreSQL with pgvector extension
+- Schema managed via Alembic migrations in `hindsight-api/alembic/`, db migrations happen during api startup, no manual commands
+- Key tables: `banks`, `memory_units`, `documents`, `entities`, `entity_links`
+
+# Branding
+## Colors
+- Primary: gradient from #0074d9 to #009296
+
@@ -4,11 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-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")
- **Opinion facts**: Beliefs with confidence scores ("Paris is beautiful" - 0.9 confidence)
- **Observations**: Complex mental models derived from reflection
+Hindsight is an agent memory system that provides long-term memory for AI agents using biomimetic data structures. It stores memories as World facts, Experiences, Opinions, and Observations across memory banks.

 ## Development Commands

@@ -17,21 +13,14 @@ Hindsight is an agent memory system that provides long-term memory for AI agents
 # Start API server (loads .env automatically)
 ./scripts/dev/start-api.sh

-# Run all tests (parallelized with pytest-xdist)
+# Run tests
 cd hindsight-api && uv run pytest tests/

 # Run specific test file
 cd hindsight-api && uv run pytest tests/test_http_api_integration.py -v

-# Run single test function
-cd hindsight-api && uv run pytest tests/test_retain.py::test_retain_simple -v
-
-# Lint and format
+# Lint
 cd hindsight-api && uv run ruff check .
-cd hindsight-api && uv run ruff format .
-
-# Type checking (uses ty - extremely fast type checker from Astral)
-cd hindsight-api && uv run ty check hindsight_api/
 ```

 ### Control Plane (Next.js)
@@ -48,7 +37,7 @@ cd hindsight-control-plane && npm run dev

 ### Generating Clients/OpenAPI
 ```bash
-# Regenerate OpenAPI spec after API changes (REQUIRED after changing endpoints)
+# Regenerate OpenAPI spec after API changes
 ./scripts/generate-openapi.sh

 # Regenerate all client SDKs (Python, TypeScript, Rust)
@@ -68,197 +57,76 @@ cd hindsight-control-plane && npm run dev
 - **hindsight-api/**: Core FastAPI server with memory engine (Python, uv)
 - **hindsight/**: Embedded Python bundle (hindsight-all package)
 - **hindsight-control-plane/**: Admin UI (Next.js, npm)
- **hindsight-cli/**: CLI tool (Rust, cargo, uses progenitor for API client)
+- **hindsight-cli/**: CLI tool (Rust, cargo)
 - **hindsight-clients/**: Generated SDK clients (Python, TypeScript, Rust)
 - **hindsight-docs/**: Docusaurus documentation site
 - **hindsight-integrations/**: Framework integrations (LiteLLM, OpenAI)
 - **hindsight-dev/**: Development tools and benchmarks

 ### Core Engine (hindsight-api/hindsight_api/engine/)
- `memory_engine.py`: Main orchestrator (~170KB) for retain/recall/reflect operations
+- `memory_engine.py`: Main orchestrator for retain/recall/reflect operations
 - `llm_wrapper.py`: LLM abstraction supporting OpenAI, Anthropic, Gemini, Groq, Ollama, LM Studio
- `embeddings.py`: Embedding generation (local sentence-transformers or TEI)
+- `embeddings.py`: Embedding generation (local or TEI)
 - `cross_encoder.py`: Reranking (local or TEI)
 - `entity_resolver.py`: Entity extraction and normalization
 - `query_analyzer.py`: Query intent analysis
-
-**retain/**: Memory ingestion pipeline
- `orchestrator.py`: Coordinates the retain flow
- `fact_extraction.py`: LLM-based fact extraction from content
- `link_utils.py`: Entity link creation and management
-
-**search/**: Multi-strategy retrieval
- `retrieval.py`: Main retrieval orchestrator
- `graph_retrieval.py`: Entity/relationship graph traversal
- `mpfp_retrieval.py`: Multi-Path Fact Propagation retrieval
- `fusion.py`: Reciprocal rank fusion for combining results
- `reranking.py`: Cross-encoder reranking
+- `retain/`: Memory ingestion pipeline
+- `search/`: Multi-strategy retrieval (semantic, BM25, graph, temporal)

 ### API Layer (hindsight-api/hindsight_api/api/)
- `http.py`: FastAPI HTTP routers (~80KB) for all REST endpoints
- `mcp.py`: Model Context Protocol server implementation
-
-Main operations:
+FastAPI routers for all endpoints. Main operations:
 - **Retain**: Store memories, extracts facts/entities/relationships
- **Recall**: Retrieve memories via 4 parallel strategies (semantic, BM25, graph, temporal) + reranking
- **Reflect**: Deep analysis forming new opinions/observations (disposition-aware)
+- **Recall**: Retrieve memories via parallel search strategies + reranking
+- **Reflect**: Deep analysis forming new opinions/observations

 ### Database
 PostgreSQL with pgvector. Schema managed via Alembic migrations in `hindsight-api/hindsight_api/alembic/`. Migrations run automatically on API startup.

 Key tables: `banks`, `memory_units`, `documents`, `entities`, `entity_links`

-### Adding Database Migrations
+### Database Backups (IMPORTANT)
+**Before any operation that may affect the database, run a backup:**
+```bash
+docker exec hindsight /backups/backup.sh
+```

-1. **Create a new migration file** in `hindsight-api/hindsight_api/alembic/versions/`:
-   - File name format: `<revision_id>_<description>.py` (e.g., `f1a2b3c4d5e6_add_new_index.py`)
-   - Use a unique hex revision ID (12 chars)
-   - Set `down_revision` to the previous migration's revision ID
+Operations requiring backup:
+- Running database migrations
+- Modifying Alembic migration files
+- Rebuilding Docker images
+- Resetting or recreating containers
+- Any schema changes
+- Bulk data operations

-2. **Migration template**:
-   ```python
-   """Description of the migration
+Backups are stored in `~/hindsight-backups/` on the host.

-   Revision ID: f1a2b3c4d5e6
-   Revises: <previous_revision_id>
-   Create Date: YYYY-MM-DD
-   """
-   from collections.abc import Sequence
-   from alembic import context, op
-
-   revision: str = "f1a2b3c4d5e6"
-   down_revision: str | Sequence[str] | None = "<previous_revision_id>"
-   branch_labels: str | Sequence[str] | None = None
-   depends_on: str | Sequence[str] | None = None
-
-   def _get_schema_prefix() -> str:
-       """Get schema prefix for table names (required for multi-tenant support)."""
-       schema = context.config.get_main_option("target_schema")
-       return f'"{schema}".' if schema else ""
-
-   def upgrade() -> None:
-       schema = _get_schema_prefix()
-       op.execute(f"CREATE INDEX ... ON {schema}table_name(...)")
-
-   def downgrade() -> None:
-       schema = _get_schema_prefix()
-       op.execute(f"DROP INDEX IF EXISTS {schema}index_name")
-   ```
-
-3. **Run migrations locally**:
-   ```bash
-   # Set database URL and run migrations
-   uv run hindsight-admin run-db-migration
-
-   # Run on a specific tenant schema
-   uv run hindsight-admin run-db-migration --schema tenant_xyz
-   ```
+To restore:
+```bash
+docker exec -it hindsight /backups/restore.sh <backup-file.sql.gz>
+```

 ## Key Conventions

-### Code Quality
-**Always run the lint script after making Python or TypeScript/Node changes:**
-```bash
-./scripts/hooks/lint.sh
-```
-This runs the same checks as the pre-commit hook (Ruff for Python, ESLint/Prettier for TypeScript).
-
 ### Memory Banks
- Each bank is an isolated memory store (like a "brain" for one user/agent)
+- Each bank is isolated (no cross-bank data access)
 - Banks have dispositions (skepticism, literalism, empathy traits 1-5) affecting reflect
 - Banks can have background context
- Bank isolation is strict - no cross-bank data leakage

 ### API Design
 - All endpoints operate on a single bank per request
- Multi-bank queries are client responsibility to orchestrate
+- Multi-bank queries are client responsibility
 - Disposition traits only affect reflect, not recall

-### Control Plane API Routes
-
-When adding or modifying parameters in the dataplane API (hindsight-api), you must also update the control plane routes that proxy to it:
-
-1. **API Routes** (`hindsight-control-plane/src/app/api/`):
-   - `recall/route.ts` - proxies to `/v1/default/banks/{bank_id}/memories/recall`
-   - `reflect/route.ts` - proxies to `/v1/default/banks/{bank_id}/reflect`
-   - `memories/retain/route.ts` - proxies to `/v1/default/banks/{bank_id}/memories/retain`
-   - Other routes follow the same pattern
-
-2. **Client types** (`hindsight-control-plane/src/lib/api.ts`):
-   - Update the TypeScript type definitions for `recall()`, `reflect()`, `retain()` etc.
-
-3. **Checklist when adding new API parameters**:
-   - Add parameter extraction in the route handler (destructure from `body`)
-   - Pass the parameter to the SDK call
-   - Update the client type definition in `lib/api.ts`
-   - Update any UI components that need to use the new parameter
-
 ### Python Style
 - Python 3.11+, type hints required
 - Async throughout (asyncpg, async FastAPI)
 - Pydantic models for request/response
 - Ruff for linting (line-length 120)
- No Python files at project root - maintain clean directory structure
- **Never use multi-item tuple return values** - prefer dataclass or Pydantic model for structured returns
-
-### Type Safety with Pydantic Models
-**NEVER use raw `dict` types for structured data.** Always use Pydantic models:
- Use Pydantic `BaseModel` for all data structures passed between functions
- Add `@field_validator` for type coercion (e.g., ensuring datetimes are timezone-aware)
- Avoid `dict.get()` patterns - use typed model attributes instead
- Parse external data (JSON, API responses) into Pydantic models at the boundary
- This catches type errors at parse time, not deep in business logic
-
-```python
-# BAD - error-prone dict access
-def process(data: dict) -> str:
-    return data.get("name", "")  # No validation, silent failures
-
-# GOOD - typed and validated
-class UserData(BaseModel):
-    name: str
-    created_at: datetime
-
-    @field_validator("created_at", mode="before")
-    @classmethod
-    def ensure_tz_aware(cls, v):
-        if isinstance(v, str):
-            v = datetime.fromisoformat(v.replace("Z", "+00:00"))
-        if v.tzinfo is None:
-            return v.replace(tzinfo=timezone.utc)
-        return v
-
-def process(data: UserData) -> str:
-    return data.name  # Type-safe, validated at construction
-```

 ### TypeScript Style
 - Next.js App Router for control plane
 - Tailwind CSS with shadcn/ui components

-### Adding New API Configuration Flags
-
-When adding a new environment variable configuration:
-
-1. **config.py** (`hindsight-api/hindsight_api/config.py`):
-   - Add `ENV_*` constant for the environment variable name
-   - Add `DEFAULT_*` constant for the default value
-   - Add field to `HindsightConfig` dataclass
-   - Add initialization in `from_env()` method
-
-2. **main.py** (`hindsight-api/hindsight_api/main.py`):
-   - Add field to the manual `HindsightConfig()` constructor call (search for "CLI override")
-
-3. **Use the config** in code:
-   ```python
-   from ...config import get_config
-   config = get_config()
-   value = config.your_new_field
-   ```
-
-4. **Documentation** (`hindsight-docs/docs/developer/configuration.md`):
-   - Add to appropriate section table with Variable, Description, Default
-
 ## Environment Setup

 ```bash
@@ -268,7 +136,7 @@ cp .env.example .env
 # Python deps
 uv sync --directory hindsight-api/

-# Node deps (uses npm workspaces)
+# Node deps (workspace)
 npm install
 ```

@@ -276,8 +144,3 @@ Required env vars:
 - `HINDSIGHT_API_LLM_PROVIDER`: openai, anthropic, gemini, groq, ollama, lmstudio
 - `HINDSIGHT_API_LLM_API_KEY`: Your API key
 - `HINDSIGHT_API_LLM_MODEL`: Model name (e.g., o3-mini, claude-sonnet-4-20250514)
-
-Optional (uses local models by default):
- `HINDSIGHT_API_EMBEDDINGS_PROVIDER`: local (default) or tei
- `HINDSIGHT_API_RERANKER_PROVIDER`: local (default) or tei
- `HINDSIGHT_API_DATABASE_URL`: External PostgreSQL (uses embedded pg0 by default)
@@ -5,7 +5,7 @@
 [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)

 [![CI](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml/badge.svg)](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml)
-[![Slack Community](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://join.slack.com/t/hindsight-space/shared_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
+[![Slack Community](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://join.slack.com/t/hindsight-space/shared_invite/zt-3klo21kua-VUCC_zHP5rIcXFB1_5yw6A)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/hindsight-api?label=PyPI)
 ![NPM Downloads](https://img.shields.io/npm/dm/%40vectorize-io%2Fhindsight-client?logoColor=orange&label=NPM&color=blue&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40vectorize-io%2Fhindsight-client)
@@ -242,7 +242,7 @@ client.reflect(bank_id="my-bank", query="What should I know about Alice?")
 - [CLI](https://hindsight.vectorize.io/sdks/cli)

 **Community:**
- [Slack](https://join.slack.com/t/hindsight-space/shared_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
+- [Slack](https://join.slack.com/t/hindsight-space/shared_invite/zt-3klo21kua-VUCC_zHP5rIcXFB1_5yw6A)
 - [GitHub Issues](https://github.com/vectorize-io/hindsight/issues)

 ---
@@ -2,24 +2,19 @@
 # Supports building API-only, Control Plane-only, or both
 #
 # Build args:
-#   INCLUDE_API=true/false         - Include API (default: true)
-#   INCLUDE_CP=true/false          - Include Control Plane (default: true)
-#   INCLUDE_LOCAL_MODELS=true/false - Include local ML models for embeddings/reranking (default: true)
-#                                     Set to false when using external providers (TEI, OpenAI, Cohere)
-#   PRELOAD_ML_MODELS=true/false   - Pre-download ML models during build (default: true)
-#                                     Only effective when INCLUDE_LOCAL_MODELS=true
+#   INCLUDE_API=true/false       - Include API (default: true)
+#   INCLUDE_CP=true/false        - Include Control Plane (default: true)
+#   PRELOAD_ML_MODELS=true/false - Pre-download ML models during build (default: true)
 #
 # Examples:
 #   docker build -t hindsight .                                          # Both (standalone)
 #   docker build -t hindsight-api --build-arg INCLUDE_CP=false .         # API only
 #   docker build -t hindsight-cp --build-arg INCLUDE_API=false .         # Control Plane only
 #   docker build -t hindsight --build-arg PRELOAD_ML_MODELS=false .      # Skip ML model preload
-#   docker build -t hindsight --build-arg INCLUDE_LOCAL_MODELS=false .   # Skip local ML deps (for external providers)

 ARG INCLUDE_API=true
 ARG INCLUDE_CP=true
 ARG PRELOAD_ML_MODELS=true
-ARG INCLUDE_LOCAL_MODELS=true

 # =============================================================================
 # Stage: API Builder
@@ -27,7 +22,6 @@ ARG INCLUDE_LOCAL_MODELS=true
 FROM python:3.11-slim AS api-builder

 ARG INCLUDE_API
-ARG INCLUDE_LOCAL_MODELS
 RUN if [ "$INCLUDE_API" != "true" ]; then echo "Skipping API build" && exit 0; fi

 WORKDIR /app
@@ -46,15 +40,6 @@ COPY hindsight-api/README.md ./api/

 WORKDIR /app/api

-# Remove local ML model dependencies if INCLUDE_LOCAL_MODELS=false
-# This creates a smaller image when using external providers (TEI, OpenAI, Cohere)
-RUN if [ "$INCLUDE_LOCAL_MODELS" != "true" ]; then \
-        echo "Removing local-models dependencies (sentence-transformers, torch, transformers)..." && \
-        sed -i '/"sentence-transformers/d' pyproject.toml && \
-        sed -i '/"transformers/d' pyproject.toml && \
-        sed -i '/"torch/d' pyproject.toml; \
-    fi
-
 # Sync dependencies (will create lock file if needed)
 RUN uv sync

@@ -168,10 +153,8 @@ USER hindsight
 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
 ARG PRELOAD_ML_MODELS
-ARG INCLUDE_LOCAL_MODELS
-RUN if [ "$PRELOAD_ML_MODELS" = "true" ] && [ "$INCLUDE_LOCAL_MODELS" = "true" ]; then \
+RUN if [ "$PRELOAD_ML_MODELS" = "true" ]; then \
    /app/api/.venv/bin/python -c "\
 from sentence_transformers import SentenceTransformer, CrossEncoder; \
 print('Downloading embedding model...'); \
@@ -179,7 +162,6 @@ SentenceTransformer('BAAI/bge-small-en-v1.5'); \
 print('Downloading cross-encoder model...'); \
 CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2'); \
 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

 EXPOSE 8888
@@ -276,10 +258,8 @@ USER hindsight
 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
 ARG PRELOAD_ML_MODELS
-ARG INCLUDE_LOCAL_MODELS
-RUN if [ "$PRELOAD_ML_MODELS" = "true" ] && [ "$INCLUDE_LOCAL_MODELS" = "true" ]; then \
+RUN if [ "$PRELOAD_ML_MODELS" = "true" ]; then \
    /app/api/.venv/bin/python -c "\
 from sentence_transformers import SentenceTransformer, CrossEncoder; \
 print('Downloading embedding model...'); \
@@ -287,7 +267,6 @@ SentenceTransformer('BAAI/bge-small-en-v1.5'); \
 print('Downloading cross-encoder model...'); \
 CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2'); \
 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

 EXPOSE 8888 9999
@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.3.0
-appVersion: "0.3.0"
+version: 0.1.16
+appVersion: "0.1.16"
 keywords:
  - ai
  - memory
@@ -80,22 +80,6 @@ Control plane selector labels
 app.kubernetes.io/component: control-plane
 {{- end }}

-{{/*
-Worker labels
-*/}}
-{{- define "hindsight.worker.labels" -}}
-{{ include "hindsight.labels" . }}
-app.kubernetes.io/component: worker
-{{- end }}
-
-{{/*
-Worker selector labels
-*/}}
-{{- define "hindsight.worker.selectorLabels" -}}
-{{ include "hindsight.selectorLabels" . }}
-app.kubernetes.io/component: worker
-{{- end }}
-
 {{/*
 Create the name of the service account to use
 */}}
@@ -126,14 +110,3 @@ API URL for control plane
 {{- define "hindsight.apiUrl" -}}
 {{- printf "http://%s-api:%d" (include "hindsight.fullname" .) (.Values.api.service.port | int) }}
 {{- end }}
-
-{{/*
-Get the name of the secret to use
-*/}}
-{{- define "hindsight.secretName" -}}
-{{- if .Values.existingSecret }}
-{{- .Values.existingSecret }}
-{{- else }}
-{{- printf "%s-secret" (include "hindsight.fullname" .) }}
-{{- end }}
-{{- end }}
@@ -15,9 +15,7 @@ spec:
  template:
    metadata:
      annotations:
-        {{- if not .Values.existingSecret }}
        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
-        {{- end }}
        {{- with .Values.podAnnotations }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
@@ -39,41 +37,27 @@ spec:
        - name: http
          containerPort: {{ .Values.api.service.targetPort }}
          protocol: TCP
-        {{- if .Values.existingSecret }}
-        envFrom:
-        - secretRef:
-            name: {{ .Values.existingSecret }}
-        {{- end }}
        env:
-        {{- /* POSTGRES_PASSWORD must be defined before DATABASE_URL for $(VAR) interpolation */}}
+        - name: HINDSIGHT_API_DATABASE_URL
+          value: {{ include "hindsight.databaseUrl" . | quote }}
        {{- if not .Values.postgresql.enabled }}
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
-              name: {{ include "hindsight.secretName" . }}
+              name: {{ include "hindsight.fullname" . }}-secret
              key: postgres-password
        {{- end }}
-        - name: HINDSIGHT_API_DATABASE_URL
-          value: {{ include "hindsight.databaseUrl" . | quote }}
-        {{- /* Disable internal worker when dedicated workers are enabled */}}
-        {{- if .Values.worker.enabled }}
-        - name: HINDSIGHT_API_WORKER_ENABLED
-          value: "false"
-        {{- end }}
        {{- range $key, $value := .Values.api.env }}
        - name: {{ $key }}
          value: {{ $value | quote }}
        {{- end }}
-        {{- /* Only use api.secrets when not using existingSecret (for chart-managed secrets) */}}
-        {{- if not .Values.existingSecret }}
        {{- range $key, $value := .Values.api.secrets }}
        - name: {{ $key }}
          valueFrom:
            secretKeyRef:
-              name: {{ include "hindsight.secretName" $ }}
+              name: {{ include "hindsight.fullname" $ }}-secret
              key: {{ $key }}
        {{- end }}
-        {{- end }}
        livenessProbe:
          {{- toYaml .Values.api.livenessProbe | nindent 10 }}
        readinessProbe:
@@ -15,9 +15,7 @@ spec:
  template:
    metadata:
      annotations:
-        {{- if not .Values.existingSecret }}
        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
-        {{- end }}
        {{- with .Values.podAnnotations }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
@@ -39,11 +37,6 @@ spec:
        - name: http
          containerPort: {{ .Values.controlPlane.service.targetPort }}
          protocol: TCP
-        {{- if .Values.existingSecret }}
-        envFrom:
-        - secretRef:
-            name: {{ .Values.existingSecret }}
-        {{- end }}
        env:
        - name: HINDSIGHT_CP_DATAPLANE_API_URL
          value: {{ include "hindsight.apiUrl" . | quote }}
@@ -51,16 +44,13 @@ spec:
        - name: {{ $key }}
          value: {{ $value | quote }}
        {{- end }}
-        {{- /* Only use controlPlane.secrets when not using existingSecret (for chart-managed secrets) */}}
-        {{- if not .Values.existingSecret }}
        {{- range $key, $value := .Values.controlPlane.secrets }}
        - name: {{ $key }}
          valueFrom:
            secretKeyRef:
-              name: {{ include "hindsight.secretName" $ }}
+              name: {{ include "hindsight.fullname" $ }}-secret
              key: {{ $key }}
        {{- end }}
-        {{- end }}
        livenessProbe:
          {{- toYaml .Values.controlPlane.livenessProbe | nindent 10 }}
        readinessProbe:
@@ -1,8 +1,7 @@
-{{- if not .Values.existingSecret }}
 apiVersion: v1
 kind: Secret
 metadata:
-  name: {{ include "hindsight.secretName" . }}
+  name: {{ include "hindsight.fullname" . }}-secret
  labels:
    {{- include "hindsight.labels" . | nindent 4 }}
 type: Opaque
@@ -16,4 +15,3 @@ data:
  {{- if and (not .Values.postgresql.enabled) .Values.postgresql.external.password }}
  postgres-password: {{ .Values.postgresql.external.password | b64enc | quote }}
  {{- end }}
-{{- end }}
@@ -1,25 +0,0 @@
-{{- if .Values.worker.enabled }}
-apiVersion: v1
-kind: Service
-metadata:
-  name: {{ include "hindsight.fullname" . }}-worker
-  labels:
-    {{- include "hindsight.worker.labels" . | nindent 4 }}
-  {{- if .Values.podAnnotations }}
-  annotations:
-    {{- /* Common Prometheus annotations for metrics scraping */}}
-    prometheus.io/scrape: "true"
-    prometheus.io/port: {{ .Values.worker.service.port | quote }}
-    prometheus.io/path: "/metrics"
-  {{- end }}
-spec:
-  # Headless service for StatefulSet (enables stable DNS names like worker-0.worker.namespace)
-  clusterIP: None
-  ports:
-  - port: {{ .Values.worker.service.port }}
-    targetPort: {{ .Values.worker.service.targetPort }}
-    protocol: TCP
-    name: http
-  selector:
-    {{- include "hindsight.worker.selectorLabels" . | nindent 4 }}
-{{- end }}
@@ -1,110 +0,0 @@
-{{- if .Values.worker.enabled }}
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: {{ include "hindsight.fullname" . }}-worker
-  labels:
-    {{- include "hindsight.worker.labels" . | nindent 4 }}
-spec:
-  serviceName: {{ include "hindsight.fullname" . }}-worker
-  replicas: {{ .Values.worker.replicaCount }}
-  selector:
-    matchLabels:
-      {{- include "hindsight.worker.selectorLabels" . | nindent 6 }}
-  template:
-    metadata:
-      annotations:
-        {{- if not .Values.existingSecret }}
-        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
-        {{- end }}
-        {{- with .Values.podAnnotations }}
-        {{- toYaml . | nindent 8 }}
-        {{- end }}
-      labels:
-        {{- include "hindsight.worker.selectorLabels" . | nindent 8 }}
-    spec:
-      {{- if .Values.serviceAccount.create }}
-      serviceAccountName: {{ include "hindsight.serviceAccountName" . }}
-      {{- end }}
-      securityContext:
-        {{- toYaml .Values.podSecurityContext | nindent 8 }}
-      containers:
-      - name: worker
-        securityContext:
-          {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.worker.image.repository }}:{{ .Values.worker.image.tag | default .Values.version }}"
-        imagePullPolicy: {{ .Values.worker.image.pullPolicy }}
-        command: ["hindsight-worker"]
-        ports:
-        - name: http
-          containerPort: {{ .Values.worker.service.targetPort }}
-          protocol: TCP
-        {{- if .Values.existingSecret }}
-        envFrom:
-        - secretRef:
-            name: {{ .Values.existingSecret }}
-        {{- end }}
-        env:
-        {{- /* POSTGRES_PASSWORD must be defined before DATABASE_URL for $(VAR) interpolation */}}
-        {{- if not .Values.postgresql.enabled }}
-        - name: POSTGRES_PASSWORD
-          valueFrom:
-            secretKeyRef:
-              name: {{ include "hindsight.secretName" . }}
-              key: postgres-password
-        {{- end }}
-        - name: HINDSIGHT_API_DATABASE_URL
-          value: {{ include "hindsight.databaseUrl" . | quote }}
-        {{- /* Worker ID uses pod name (StatefulSet provides stable names like worker-0, worker-1) */}}
-        - name: HINDSIGHT_API_WORKER_ID
-          valueFrom:
-            fieldRef:
-              fieldPath: metadata.name
-        {{- /* Inherit LLM config from api.env */}}
-        {{- range $key, $value := .Values.api.env }}
-        - name: {{ $key }}
-          value: {{ $value | quote }}
-        {{- end }}
-        {{- /* Worker-specific env vars */}}
-        {{- range $key, $value := .Values.worker.env }}
-        - name: {{ $key }}
-          value: {{ $value | quote }}
-        {{- end }}
-        {{- /* Only use secrets when not using existingSecret */}}
-        {{- if not .Values.existingSecret }}
-        {{- /* Inherit secrets from api.secrets */}}
-        {{- range $key, $value := .Values.api.secrets }}
-        - name: {{ $key }}
-          valueFrom:
-            secretKeyRef:
-              name: {{ include "hindsight.secretName" $ }}
-              key: {{ $key }}
-        {{- end }}
-        {{- /* Worker-specific secrets (can override api.secrets) */}}
-        {{- range $key, $value := .Values.worker.secrets }}
-        - name: {{ $key }}
-          valueFrom:
-            secretKeyRef:
-              name: {{ include "hindsight.secretName" $ }}
-              key: {{ $key }}
-        {{- end }}
-        {{- end }}
-        livenessProbe:
-          {{- toYaml .Values.worker.livenessProbe | nindent 10 }}
-        readinessProbe:
-          {{- toYaml .Values.worker.readinessProbe | nindent 10 }}
-        resources:
-          {{- toYaml .Values.worker.resources | nindent 10 }}
-      {{- with .Values.nodeSelector }}
-      nodeSelector:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.affinity }}
-      affinity:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.tolerations }}
-      tolerations:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-{{- end }}
@@ -3,15 +3,6 @@
 # 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
-# Required keys:
-#   - postgres-password: PostgreSQL password (when postgresql.enabled=false)
-# Optional keys (any key becomes an env var):
-#   - HINDSIGHT_API_LLM_API_KEY: API key for LLM provider
-#   - Any other env vars you want to inject
-# existingSecret: "my-hindsight-secret"
-
 # Global settings
 replicaCount: 1

@@ -67,63 +58,6 @@ api:
    # HINDSIGHT_API_LLM_API_KEY: "your-api-key"
    # HINDSIGHT_API_LLM_BASE_URL: "https://api.groq.com/openai/v1"

-# Worker settings (distributed task processing)
-# When enabled, dedicated worker pods process tasks and the API's internal worker is disabled
-worker:
-  enabled: false
-  replicaCount: 2
-  image:
-    repository: ghcr.io/vectorize-io/hindsight-api
-    pullPolicy: IfNotPresent
-    # tag defaults to .Values.version if not specified
-
-  service:
-    # Service for metrics scraping (headless for StatefulSet)
-    port: 8889
-    targetPort: 8889
-
-  # Resource limits and requests
-  resources:
-    limits:
-      cpu: 2000m
-      memory: 4Gi
-    requests:
-      cpu: 500m
-      memory: 1Gi
-
-  # Liveness and readiness probes
-  livenessProbe:
-    httpGet:
-      path: /health
-      port: 8889
-    initialDelaySeconds: 30
-    periodSeconds: 10
-    timeoutSeconds: 5
-    failureThreshold: 3
-
-  readinessProbe:
-    httpGet:
-      path: /health
-      port: 8889
-    initialDelaySeconds: 10
-    periodSeconds: 5
-    timeoutSeconds: 3
-    failureThreshold: 3
-
-  # Worker-specific environment variables
-  env:
-    # Poll interval in milliseconds (how often to check for new tasks)
-    HINDSIGHT_API_WORKER_POLL_INTERVAL_MS: "500"
-    # Number of tasks to claim per poll cycle
-    HINDSIGHT_API_WORKER_BATCH_SIZE: "10"
-    # Max retries before marking a task as failed
-    HINDSIGHT_API_WORKER_MAX_RETRIES: "3"
-    # HTTP port for metrics/health (matches service.targetPort)
-    HINDSIGHT_API_WORKER_HTTP_PORT: "8889"
-
-  # Secret environment variables (inherited from api.secrets if not specified)
-  secrets: {}
-
 # Image settings for control plane
 controlPlane:
  enabled: true
@@ -1 +0,0 @@
-# Admin CLI for Hindsight
@@ -1,311 +0,0 @@
-"""
-Hindsight Admin CLI - backup and restore operations.
-"""
-
-import asyncio
-import io
-import json
-import logging
-import zipfile
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-
-import asyncpg
-import typer
-
-from ..config import HindsightConfig
-from ..pg0 import parse_pg0_url, resolve_database_url
-
-
-def _fq_table(table: str, schema: str) -> str:
-    """Get fully-qualified table name with schema prefix."""
-    return f"{schema}.{table}"
-
-
-# Setup logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(message)s",
-)
-logger = logging.getLogger(__name__)
-
-app = typer.Typer(name="hindsight-admin", help="Hindsight administrative commands")
-
-# Tables to backup/restore in dependency order
-# Import must happen in this order due to foreign key constraints
-BACKUP_TABLES = [
-    "banks",
-    "documents",
-    "entities",
-    "chunks",
-    "memory_units",
-    "unit_entities",
-    "entity_cooccurrences",
-    "memory_links",
-]
-
-MANIFEST_VERSION = "1"
-
-
-async def _backup(database_url: str, output_path: Path, schema: str = "public") -> dict[str, Any]:
-    """Backup all tables to a zip file using binary COPY protocol."""
-    conn = await asyncpg.connect(database_url)
-    try:
-        tables: dict[str, Any] = {}
-        manifest: dict[str, Any] = {
-            "version": MANIFEST_VERSION,
-            "created_at": datetime.now(timezone.utc).isoformat(),
-            "schema": schema,
-            "tables": tables,
-        }
-
-        # Use a transaction with REPEATABLE READ isolation to get a consistent
-        # snapshot across all tables. This prevents race conditions where
-        # entity_cooccurrences could reference entities created after the
-        # entities table was backed up.
-        async with conn.transaction(isolation="repeatable_read"):
-            with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
-                for i, table in enumerate(BACKUP_TABLES, 1):
-                    typer.echo(f"  [{i}/{len(BACKUP_TABLES)}] Backing up {table}...", nl=False)
-
-                    buffer = io.BytesIO()
-
-                    # Use binary COPY for exact type preservation
-                    # asyncpg requires schema_name as separate parameter
-                    await conn.copy_from_table(table, schema_name=schema, output=buffer, format="binary")
-
-                    data = buffer.getvalue()
-                    zf.writestr(f"{table}.bin", data)
-
-                    # Get row count for manifest
-                    qualified_table = _fq_table(table, schema)
-                    row_count = await conn.fetchval(f"SELECT COUNT(*) FROM {qualified_table}")
-                    tables[table] = {
-                        "rows": row_count,
-                        "size_bytes": len(data),
-                    }
-
-                    typer.echo(f" {row_count} rows")
-
-                zf.writestr("manifest.json", json.dumps(manifest, indent=2))
-
-        return manifest
-    finally:
-        await conn.close()
-
-
-async def _restore(database_url: str, input_path: Path, schema: str = "public") -> dict[str, Any]:
-    """Restore all tables from a zip file using binary COPY protocol."""
-    conn = await asyncpg.connect(database_url)
-    try:
-        with zipfile.ZipFile(input_path, "r") as zf:
-            # Read and validate manifest
-            manifest: dict[str, Any] = json.loads(zf.read("manifest.json"))
-            if manifest.get("version") != MANIFEST_VERSION:
-                raise ValueError(f"Unsupported backup version: {manifest.get('version')}")
-
-            # Use a transaction for atomic restore - either all tables are
-            # restored or none are, preventing partial/inconsistent state.
-            async with conn.transaction():
-                typer.echo("  Clearing existing data...")
-                # Truncate tables in reverse order (respects FK constraints)
-                for table in reversed(BACKUP_TABLES):
-                    qualified_table = _fq_table(table, schema)
-                    await conn.execute(f"TRUNCATE TABLE {qualified_table} CASCADE")
-
-                # Restore tables in forward order
-                for i, table in enumerate(BACKUP_TABLES, 1):
-                    filename = f"{table}.bin"
-                    if filename not in zf.namelist():
-                        typer.echo(f"  [{i}/{len(BACKUP_TABLES)}] {table}: skipped (not in backup)")
-                        continue
-
-                    expected_rows = manifest["tables"].get(table, {}).get("rows", "?")
-                    typer.echo(f"  [{i}/{len(BACKUP_TABLES)}] Restoring {table}... {expected_rows} rows")
-
-                    data = zf.read(filename)
-                    buffer = io.BytesIO(data)
-                    # asyncpg requires schema_name as separate parameter
-                    await conn.copy_to_table(table, schema_name=schema, source=buffer, format="binary")
-
-                # Refresh materialized view
-                typer.echo("  Refreshing materialized views...")
-                await conn.execute(f"REFRESH MATERIALIZED VIEW {_fq_table('memory_units_bm25', schema)}")
-
-        return manifest
-    finally:
-        await conn.close()
-
-
-async def _run_backup(db_url: str, output: Path, schema: str = "public") -> dict[str, Any]:
-    """Resolve database URL and run backup."""
-    is_pg0, instance_name, _ = parse_pg0_url(db_url)
-    if is_pg0:
-        typer.echo(f"Starting embedded PostgreSQL (instance: {instance_name})...")
-    resolved_url = await resolve_database_url(db_url)
-    return await _backup(resolved_url, output, schema)
-
-
-async def _run_restore(db_url: str, input_file: Path, schema: str = "public") -> dict[str, Any]:
-    """Resolve database URL and run restore."""
-    is_pg0, instance_name, _ = parse_pg0_url(db_url)
-    if is_pg0:
-        typer.echo(f"Starting embedded PostgreSQL (instance: {instance_name})...")
-    resolved_url = await resolve_database_url(db_url)
-    return await _restore(resolved_url, input_file, schema)
-
-
-@app.command()
-def backup(
-    output: Path = typer.Argument(..., help="Output file path (.zip)"),
-    schema: str = typer.Option("public", "--schema", "-s", help="Database schema to backup"),
-):
-    """Backup the Hindsight database to a zip file."""
-    config = HindsightConfig.from_env()
-
-    if not config.database_url:
-        typer.echo("Error: Database URL not configured.", err=True)
-        typer.echo("Set HINDSIGHT_API_DATABASE_URL environment variable.", err=True)
-        raise typer.Exit(1)
-
-    if output.suffix != ".zip":
-        output = output.with_suffix(".zip")
-
-    typer.echo(f"Backing up database (schema: {schema}) to {output}...")
-
-    manifest = asyncio.run(_run_backup(config.database_url, output, schema))
-
-    total_rows = sum(t["rows"] for t in manifest["tables"].values())
-    typer.echo(f"Backed up {total_rows} rows across {len(BACKUP_TABLES)} tables")
-    typer.echo(f"Backup saved to {output}")
-
-
-@app.command()
-def restore(
-    input_file: Path = typer.Argument(..., help="Input backup file (.zip)"),
-    schema: str = typer.Option("public", "--schema", "-s", help="Database schema to restore to"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
-):
-    """Restore the database from a backup file. WARNING: This deletes all existing data."""
-    config = HindsightConfig.from_env()
-
-    if not config.database_url:
-        typer.echo("Error: Database URL not configured.", err=True)
-        typer.echo("Set HINDSIGHT_API_DATABASE_URL environment variable.", err=True)
-        raise typer.Exit(1)
-
-    if not input_file.exists():
-        typer.echo(f"Error: File not found: {input_file}", err=True)
-        raise typer.Exit(1)
-
-    if not yes:
-        typer.confirm(
-            "This will DELETE all existing data and replace it with the backup. Continue?",
-            abort=True,
-        )
-
-    typer.echo(f"Restoring database (schema: {schema}) from {input_file}...")
-
-    manifest = asyncio.run(_run_restore(config.database_url, input_file, schema))
-
-    total_rows = sum(t["rows"] for t in manifest["tables"].values())
-    typer.echo(f"Restored {total_rows} rows across {len(BACKUP_TABLES)} tables")
-    typer.echo("Restore complete")
-
-
-async def _run_migration(db_url: str, schema: str = "public") -> None:
-    """Resolve database URL and run migrations."""
-    from ..migrations import run_migrations
-
-    is_pg0, instance_name, _ = parse_pg0_url(db_url)
-    if is_pg0:
-        typer.echo(f"Starting embedded PostgreSQL (instance: {instance_name})...")
-    resolved_url = await resolve_database_url(db_url)
-    run_migrations(resolved_url, schema=schema)
-
-
-@app.command(name="run-db-migration")
-def run_db_migration(
-    schema: str = typer.Option("public", "--schema", "-s", help="Database schema to run migrations on"),
-):
-    """Run database migrations to the latest version."""
-    config = HindsightConfig.from_env()
-
-    if not config.database_url:
-        typer.echo("Error: Database URL not configured.", err=True)
-        typer.echo("Set HINDSIGHT_API_DATABASE_URL environment variable.", err=True)
-        raise typer.Exit(1)
-
-    typer.echo(f"Running database migrations (schema: {schema})...")
-
-    asyncio.run(_run_migration(config.database_url, schema))
-
-    typer.echo("Database migrations completed successfully")
-
-
-async def _decommission_worker(db_url: str, worker_id: str, schema: str = "public") -> int:
-    """Release all tasks owned by a worker, setting them back to pending status."""
-    is_pg0, instance_name, _ = parse_pg0_url(db_url)
-    if is_pg0:
-        typer.echo(f"Starting embedded PostgreSQL (instance: {instance_name})...")
-    resolved_url = await resolve_database_url(db_url)
-
-    conn = await asyncpg.connect(resolved_url)
-    try:
-        table = _fq_table("async_operations", schema)
-        result = await conn.fetch(
-            f"""
-            UPDATE {table}
-            SET status = 'pending', worker_id = NULL, claimed_at = NULL, updated_at = now()
-            WHERE worker_id = $1 AND status = 'processing'
-            RETURNING operation_id
-            """,
-            worker_id,
-        )
-        return len(result)
-    finally:
-        await conn.close()
-
-
-@app.command(name="decommission-worker")
-def decommission_worker(
-    worker_id: str = typer.Argument(..., help="Worker ID to decommission"),
-    schema: str = typer.Option("public", "--schema", "-s", help="Database schema"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
-):
-    """Release all tasks owned by a worker (sets status back to pending).
-
-    Use this command when a worker has crashed or been removed without graceful shutdown.
-    All tasks that were being processed by the worker will be released back to the queue
-    so other workers can pick them up.
-    """
-    config = HindsightConfig.from_env()
-
-    if not config.database_url:
-        typer.echo("Error: Database URL not configured.", err=True)
-        typer.echo("Set HINDSIGHT_API_DATABASE_URL environment variable.", err=True)
-        raise typer.Exit(1)
-
-    if not yes:
-        typer.confirm(
-            f"This will release all tasks owned by worker '{worker_id}' back to pending. Continue?",
-            abort=True,
-        )
-
-    typer.echo(f"Decommissioning worker '{worker_id}' (schema: {schema})...")
-
-    count = asyncio.run(_decommission_worker(config.database_url, worker_id, schema))
-
-    if count > 0:
-        typer.echo(f"Released {count} task(s) from worker '{worker_id}'")
-    else:
-        typer.echo(f"No tasks found for worker '{worker_id}'")
-
-
-def main():
-    app()
-
-
-if __name__ == "__main__":
-    main()
@@ -1,44 +0,0 @@
-"""add_memory_links_from_type_weight_index
-
-Revision ID: f1a2b3c4d5e6
-Revises: e0a1b2c3d4e5
-Create Date: 2025-01-12
-
-Add composite index on memory_links (from_unit_id, link_type, weight DESC)
-to optimize MPFP graph traversal queries that need top-k edges per type.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "f1a2b3c4d5e6"
-down_revision: str | Sequence[str] | None = "e0a1b2c3d4e5"
-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 (e.g., 'tenant_x.' or '' for public)."""
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    """Add composite index for efficient MPFP edge loading."""
-    schema = _get_schema_prefix()
-    # Create composite index for efficient top-k per (from_node, link_type) queries
-    # This enables LATERAL joins to use index-only scans with early termination
-    # Note: Not using CONCURRENTLY here as it requires running outside a transaction
-    # For production with large tables, consider running this manually with CONCURRENTLY
-    op.execute(
-        f"CREATE INDEX IF NOT EXISTS idx_memory_links_from_type_weight "
-        f"ON {schema}memory_links(from_unit_id, link_type, weight DESC)"
-    )
-
-
-def downgrade() -> None:
-    """Remove the composite index."""
-    schema = _get_schema_prefix()
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_links_from_type_weight")
@@ -1,48 +0,0 @@
-"""add_tags_column
-
-Revision ID: g2a3b4c5d6e7
-Revises: f1a2b3c4d5e6
-Create Date: 2025-01-13
-
-Add tags column to memory_units and documents tables for visibility scoping.
-Tags enable filtering memories by scope (e.g., user IDs, session IDs) during recall/reflect.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "g2a3b4c5d6e7"
-down_revision: str | Sequence[str] | None = "f1a2b3c4d5e6"
-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 (e.g., 'tenant_x.' or '' for public)."""
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    """Add tags column to memory_units and documents tables."""
-    schema = _get_schema_prefix()
-
-    # Add tags column to memory_units table
-    op.execute(f"ALTER TABLE {schema}memory_units ADD COLUMN IF NOT EXISTS tags VARCHAR[] NOT NULL DEFAULT '{{}}'")
-
-    # Create GIN index for efficient array containment queries (tags && ARRAY['x'])
-    op.execute(f"CREATE INDEX IF NOT EXISTS idx_memory_units_tags ON {schema}memory_units USING GIN (tags)")
-
-    # Add tags column to documents table for document-level tags
-    op.execute(f"ALTER TABLE {schema}documents ADD COLUMN IF NOT EXISTS tags VARCHAR[] NOT NULL DEFAULT '{{}}'")
-
-
-def downgrade() -> None:
-    """Remove tags columns and index."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_tags")
-    op.execute(f"ALTER TABLE {schema}memory_units DROP COLUMN IF EXISTS tags")
-    op.execute(f"ALTER TABLE {schema}documents DROP COLUMN IF EXISTS tags")
@@ -1,112 +0,0 @@
-"""mental_models_v4
-
-Revision ID: h3c4d5e6f7g8
-Revises: g2a3b4c5d6e7
-Create Date: 2026-01-08 00:00:00.000000
-
-This migration implements the v4 mental models system:
-1. Deletes existing observation memory_units (observations now in mental models)
-2. Adds mission column to banks (replacing background)
-3. Creates mental_models table with final schema
-
-Mental models can reference entities when an entity is "promoted" to a mental model.
-Summary content is stored as JSONB observations with per-observation fact attribution.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "h3c4d5e6f7g8"
-down_revision: str | Sequence[str] | None = "g2a3b4c5d6e7"
-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:
-    """Apply mental models v4 changes."""
-    schema = _get_schema_prefix()
-
-    # Step 1: Delete observation memory_units (cascades to unit_entities links)
-    # Observations are now handled through mental models, not memory_units
-    op.execute(f"DELETE FROM {schema}memory_units WHERE fact_type = 'observation'")
-
-    # Step 2: Drop observation-specific index (if it exists)
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_observation_date")
-
-    # Step 3: Add mission column to banks (replacing background)
-    op.execute(f"ALTER TABLE {schema}banks ADD COLUMN IF NOT EXISTS mission TEXT")
-
-    # Migrate: copy background to mission if background column exists
-    # Use DO block to check column existence first (idempotent for re-runs)
-    schema_name = context.config.get_main_option("target_schema") or "public"
-    op.execute(f"""
-        DO $$
-        BEGIN
-            IF EXISTS (
-                SELECT 1 FROM information_schema.columns
-                WHERE table_schema = '{schema_name}' AND table_name = 'banks' AND column_name = 'background'
-            ) THEN
-                UPDATE {schema}banks
-                SET mission = background
-                WHERE mission IS NULL;
-            END IF;
-        END $$;
-    """)
-
-    # Remove background column (replaced by mission)
-    op.execute(f"ALTER TABLE {schema}banks DROP COLUMN IF EXISTS background")
-
-    # Step 4: Create mental_models table with final v4 schema (if not exists)
-    op.execute(f"""
-        CREATE TABLE IF NOT EXISTS {schema}mental_models (
-            id VARCHAR(64) NOT NULL,
-            bank_id VARCHAR(64) NOT NULL,
-            subtype VARCHAR(32) NOT NULL,
-            name VARCHAR(256) NOT NULL,
-            description TEXT NOT NULL,
-            entity_id UUID,
-            observations JSONB DEFAULT '{{"observations": []}}'::jsonb,
-            links VARCHAR[],
-            tags VARCHAR[] DEFAULT '{{}}',
-            last_updated TIMESTAMP WITH TIME ZONE,
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
-            PRIMARY KEY (id, bank_id),
-            FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE,
-            FOREIGN KEY (entity_id) REFERENCES {schema}entities(id) ON DELETE SET NULL,
-            CONSTRAINT ck_mental_models_subtype CHECK (subtype IN ('structural', 'emergent', 'pinned', 'learned'))
-        )
-    """)
-
-    # Step 5: Create indexes for efficient queries (if not exist)
-    op.execute(f"CREATE INDEX IF NOT EXISTS idx_mental_models_bank_id ON {schema}mental_models(bank_id)")
-    op.execute(f"CREATE INDEX IF NOT EXISTS idx_mental_models_subtype ON {schema}mental_models(bank_id, subtype)")
-    op.execute(f"CREATE INDEX IF NOT EXISTS idx_mental_models_entity_id ON {schema}mental_models(entity_id)")
-    # GIN index for efficient tags array filtering
-    op.execute(f"CREATE INDEX IF NOT EXISTS idx_mental_models_tags ON {schema}mental_models USING GIN(tags)")
-
-
-def downgrade() -> None:
-    """Revert mental models v4 changes."""
-    schema = _get_schema_prefix()
-
-    # Drop mental_models table (cascades to indexes)
-    op.execute(f"DROP TABLE IF EXISTS {schema}mental_models CASCADE")
-
-    # Add back background column to banks
-    op.execute(f"ALTER TABLE {schema}banks ADD COLUMN IF NOT EXISTS background TEXT")
-
-    # Migrate mission back to background
-    op.execute(f"UPDATE {schema}banks SET background = mission WHERE background IS NULL")
-
-    # Remove mission column
-    op.execute(f"ALTER TABLE {schema}banks DROP COLUMN IF EXISTS mission")
-
-    # Note: Cannot restore deleted observations - they are lost on downgrade
@@ -1,41 +0,0 @@
-"""delete_opinions
-
-Revision ID: i4d5e6f7g8h9
-Revises: h3c4d5e6f7g8
-Create Date: 2026-01-15 00:00:00.000000
-
-This migration removes opinion facts from memory_units.
-Opinions are no longer a separate fact type - they are now represented
-through mental model observations with confidence scores.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "i4d5e6f7g8h9"
-down_revision: str | Sequence[str] | None = "h3c4d5e6f7g8"
-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:
-    """Delete opinion memory_units."""
-    schema = _get_schema_prefix()
-
-    # Delete opinion memory_units (cascades to unit_entities links)
-    # Opinions are now handled through mental model observations
-    op.execute(f"DELETE FROM {schema}memory_units WHERE fact_type = 'opinion'")
-
-
-def downgrade() -> None:
-    """Cannot restore deleted opinions."""
-    # Note: Cannot restore deleted opinions - they are lost on downgrade
-    pass
@@ -1,95 +0,0 @@
-"""mental_model_versions
-
-Revision ID: j5e6f7g8h9i0
-Revises: i4d5e6f7g8h9
-Create Date: 2026-01-16 00:00:00.000000
-
-This migration adds versioning support for mental models:
-1. Creates mental_model_versions table to store observation snapshots
-2. Adds version column to mental_models for tracking current version
-
-This enables changelog/diff functionality for mental model observations.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "j5e6f7g8h9i0"
-down_revision: str | Sequence[str] | None = "i4d5e6f7g8h9"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    """Get schema prefix for table names (required for multi-tenant support)."""
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    """Create mental_model_versions table and add version tracking."""
-    schema = _get_schema_prefix()
-
-    # Create mental_model_versions table for storing observation snapshots
-    op.execute(f"""
-        CREATE TABLE {schema}mental_model_versions (
-            id SERIAL PRIMARY KEY,
-            mental_model_id VARCHAR(64) NOT NULL,
-            bank_id VARCHAR(64) NOT NULL,
-            version INT NOT NULL,
-            observations JSONB NOT NULL DEFAULT '{{"observations": []}}'::jsonb,
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
-            FOREIGN KEY (mental_model_id, bank_id)
-                REFERENCES {schema}mental_models(id, bank_id) ON DELETE CASCADE,
-            UNIQUE (mental_model_id, bank_id, version)
-        )
-    """)
-
-    # Index for efficient version queries (get latest, list versions)
-    op.execute(f"""
-        CREATE INDEX idx_mental_model_versions_lookup
-        ON {schema}mental_model_versions(mental_model_id, bank_id, version DESC)
-    """)
-
-    # Add version column to mental_models to track current version
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD COLUMN IF NOT EXISTS version INT NOT NULL DEFAULT 0
-    """)
-
-    # Migrate existing mental models: create version 1 for any that have observations
-    op.execute(f"""
-        INSERT INTO {schema}mental_model_versions (mental_model_id, bank_id, version, observations, created_at)
-        SELECT id, bank_id, 1, observations, COALESCE(last_updated, created_at)
-        FROM {schema}mental_models
-        WHERE observations IS NOT NULL
-          AND observations != '{{"observations": []}}'::jsonb
-          AND (observations->'observations') IS NOT NULL
-          AND jsonb_array_length(observations->'observations') > 0
-    """)
-
-    # Update version to 1 for migrated mental models
-    op.execute(f"""
-        UPDATE {schema}mental_models
-        SET version = 1
-        WHERE observations IS NOT NULL
-          AND observations != '{{"observations": []}}'::jsonb
-          AND (observations->'observations') IS NOT NULL
-          AND jsonb_array_length(observations->'observations') > 0
-    """)
-
-
-def downgrade() -> None:
-    """Remove mental_model_versions table and version column."""
-    schema = _get_schema_prefix()
-
-    # Drop index
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_mental_model_versions_lookup")
-
-    # Drop versions table
-    op.execute(f"DROP TABLE IF EXISTS {schema}mental_model_versions")
-
-    # Remove version column from mental_models
-    op.execute(f"ALTER TABLE {schema}mental_models DROP COLUMN IF EXISTS version")
@@ -1,58 +0,0 @@
-"""add_directive_subtype
-
-Revision ID: k6f7g8h9i0j1
-Revises: j5e6f7g8h9i0
-Create Date: 2026-01-16 00:00:00.000000
-
-This migration adds 'directive' to the mental_models subtype constraint.
-Directives are hard rules with user-provided observations that the reflect agent must follow.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "k6f7g8h9i0j1"
-down_revision: str | Sequence[str] | None = "j5e6f7g8h9i0"
-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 'directive' to mental_models subtype constraint."""
-    schema = _get_schema_prefix()
-
-    # Drop existing constraint
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS ck_mental_models_subtype")
-
-    # Create new constraint with 'directive' added
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT ck_mental_models_subtype
-        CHECK (subtype IN ('structural', 'emergent', 'pinned', 'learned', 'directive'))
-    """)
-
-
-def downgrade() -> None:
-    """Remove 'directive' from mental_models subtype constraint."""
-    schema = _get_schema_prefix()
-
-    # First delete any directives (cannot downgrade if they exist)
-    op.execute(f"DELETE FROM {schema}mental_models WHERE subtype = 'directive'")
-
-    # Drop constraint with directive
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS ck_mental_models_subtype")
-
-    # Recreate original constraint without directive
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT ck_mental_models_subtype
-        CHECK (subtype IN ('structural', 'emergent', 'pinned', 'learned'))
-    """)
@@ -1,109 +0,0 @@
-"""add_worker_columns
-
-Revision ID: l7g8h9i0j1k2
-Revises: k6f7g8h9i0j1
-Create Date: 2026-01-19 00:00:00.000000
-
-This migration adds columns to async_operations for distributed worker support:
- worker_id: ID of the worker that claimed the task
- claimed_at: When the task was claimed
- retry_count: Number of retry attempts
- task_payload: The serialized task dictionary
-"""
-
-from collections.abc import Sequence
-
-import sqlalchemy as sa
-from alembic import context, op
-from sqlalchemy.dialects import postgresql
-
-# revision identifiers, used by Alembic.
-revision: str = "l7g8h9i0j1k2"
-down_revision: str | Sequence[str] | None = "k6f7g8h9i0j1"
-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 worker columns to async_operations."""
-    schema = _get_schema_prefix()
-
-    # Add worker_id column (ID of worker that claimed the task)
-    op.add_column(
-        "async_operations",
-        sa.Column("worker_id", sa.Text(), nullable=True),
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-
-    # Add claimed_at column (when task was claimed by worker)
-    op.add_column(
-        "async_operations",
-        sa.Column("claimed_at", postgresql.TIMESTAMP(timezone=True), nullable=True),
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-
-    # Add retry_count column (number of retry attempts)
-    op.add_column(
-        "async_operations",
-        sa.Column("retry_count", sa.Integer(), server_default="0", nullable=False),
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-
-    # Add task_payload column (serialized task dictionary)
-    op.add_column(
-        "async_operations",
-        sa.Column(
-            "task_payload",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=True,
-        ),
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-
-    # Add index for efficient worker polling (pending tasks ordered by creation time)
-    op.execute(
-        f"CREATE INDEX idx_async_operations_pending_claim ON {schema}async_operations (status, created_at) "
-        f"WHERE status = 'pending' AND task_payload IS NOT NULL"
-    )
-
-    # Add index for finding tasks by worker_id (for decommissioning)
-    op.execute(
-        f"CREATE INDEX idx_async_operations_worker_id ON {schema}async_operations (worker_id) WHERE worker_id IS NOT NULL"
-    )
-
-
-def downgrade() -> None:
-    """Remove worker columns from async_operations."""
-    schema = _get_schema_prefix()
-
-    # Drop indexes
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_async_operations_pending_claim")
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_async_operations_worker_id")
-
-    # Drop columns
-    op.drop_column(
-        "async_operations",
-        "task_payload",
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-    op.drop_column(
-        "async_operations",
-        "retry_count",
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-    op.drop_column(
-        "async_operations",
-        "claimed_at",
-        schema=context.config.get_main_option("target_schema") or None,
-    )
-    op.drop_column(
-        "async_operations",
-        "worker_id",
-        schema=context.config.get_main_option("target_schema") or None,
-    )
@@ -8,6 +8,7 @@ from contextvars import ContextVar
 from fastmcp import FastMCP

 from hindsight_api import MemoryEngine
+from hindsight_api.api.http import BankListItem, BankListResponse, BankProfileResponse, DispositionTraits
 from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
 from hindsight_api.models import RequestContext

@@ -53,12 +54,7 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
    mcp = FastMCP("hindsight-mcp-server", stateless_http=True)

    @mcp.tool()
-    async def retain(
-        content: str,
-        context: str = "general",
-        async_processing: bool = True,
-        bank_id: str | None = None,
-    ) -> str:
+    async def retain(content: str, context: str = "general", bank_id: str | None = None) -> str:
        """
        Store important information to long-term memory.

@@ -74,28 +70,18 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
        Args:
            content: The fact/memory to store (be specific and include relevant details)
            context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
-            async_processing: If True, queue for background processing and return immediately. If False, wait for completion. Default: True
            bank_id: Optional bank to store in (defaults to session bank). Use for cross-bank operations.
        """
        try:
            target_bank = bank_id or get_current_bank_id()
            if target_bank is None:
                return "Error: No bank_id configured"
-            contents = [{"content": content, "context": context}]
-            if async_processing:
-                # Queue for background processing and return immediately
-                result = await memory.submit_async_retain(
-                    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:
-                # Wait for completion
-                await memory.retain_batch_async(
-                    bank_id=target_bank,
-                    contents=contents,
-                    request_context=RequestContext(),
-                )
-                return f"Memory stored successfully in bank '{target_bank}'"
+            await memory.retain_batch_async(
+                bank_id=target_bank,
+                contents=[{"content": content, "context": context}],
+                request_context=RequestContext(),
+            )
+            return f"Memory stored successfully in bank '{target_bank}'"
        except Exception as e:
            logger.error(f"Error storing memory: {e}", exc_info=True)
            return f"Error: {str(e)}"
@@ -192,54 +178,73 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
        """
        List all available memory banks.

-        Use this tool to discover what memory banks exist in the system.
-        Each bank is an isolated memory store (like a separate "brain").
+        Use this to discover banks for orchestration or to find
+        the correct bank_id for cross-bank operations.

        Returns:
-            JSON list of banks with their IDs, names, dispositions, and missions.
+            JSON object with banks array containing bank_id, name, disposition, background, and timestamps
        """
        try:
            banks = await memory.list_banks(request_context=RequestContext())
-            return json.dumps({"banks": banks}, indent=2)
+            bank_items = [
+                BankListItem(
+                    bank_id=b.get("bank_id") or b.get("id"),
+                    name=b.get("name"),
+                    disposition=DispositionTraits(
+                        **b.get("disposition", {"skepticism": 3, "literalism": 3, "empathy": 3})
+                    ),
+                    background=b.get("background"),
+                    created_at=str(b.get("created_at")) if b.get("created_at") else None,
+                    updated_at=str(b.get("updated_at")) if b.get("updated_at") else None,
+                )
+                for b in banks
+            ]
+            return BankListResponse(banks=bank_items).model_dump_json(indent=2)
        except Exception as e:
            logger.error(f"Error listing banks: {e}", exc_info=True)
            return f'{{"error": "{e}", "banks": []}}'

    @mcp.tool()
-    async def create_bank(bank_id: str, name: str | None = None, mission: str | None = None) -> str:
+    async def create_bank(bank_id: str, name: str | None = None, background: str | None = None) -> str:
        """
-        Create a new memory bank or get an existing one.
+        Create or update a memory bank.

-        Memory banks are isolated stores - each one is like a separate "brain" for a user/agent.
-        Banks are auto-created with default settings if they don't exist.
+        Use this to create new banks for different agents, sessions, or purposes.
+        Banks are isolated memory stores - each bank has its own memories and personality.

        Args:
-            bank_id: Unique identifier for the bank (e.g., 'user-123', 'agent-alpha')
-            name: Optional human-friendly name for the bank
-            mission: Optional mission describing who the agent is and what they're trying to accomplish
+            bank_id: Unique identifier for the bank (e.g., 'orchestrator-memory', 'agent-1')
+            name: Human-readable name for the bank
+            background: Context about what this bank stores or its purpose
        """
        try:
-            # get_bank_profile auto-creates bank if it doesn't exist
+            # Get or create the bank profile (auto-creates with defaults)
+            await memory.get_bank_profile(bank_id, request_context=RequestContext())
+
+            # Update name and/or background if provided
+            if name is not None or background is not None:
+                await memory.update_bank(bank_id, name=name, background=background, request_context=RequestContext())
+
+            # Get final profile and return using BankProfileResponse model
            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:
-                await memory.update_bank(
-                    bank_id,
-                    name=name,
-                    mission=mission,
-                    request_context=RequestContext(),
+            disposition = profile.get("disposition")
+            if hasattr(disposition, "model_dump"):
+                disposition_traits = DispositionTraits(**disposition.model_dump())
+            else:
+                disposition_traits = DispositionTraits(
+                    **dict(disposition or {"skepticism": 3, "literalism": 3, "empathy": 3})
                )
-                # Fetch updated profile
-                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"):
-                profile["disposition"] = profile["disposition"].model_dump()
-            return json.dumps(profile, indent=2)
+            response = BankProfileResponse(
+                bank_id=bank_id,
+                name=profile.get("name") or "",
+                disposition=disposition_traits,
+                background=profile.get("background") or "",
+            )
+            return response.model_dump_json(indent=2)
        except Exception as e:
            logger.error(f"Error creating bank: {e}", exc_info=True)
-            return f'{{"error": "{e}"}}'
+            return json.dumps({"error": str(e)})

    return mcp

@@ -4,17 +4,9 @@ Centralized configuration for Hindsight API.
 All environment variables and their defaults are defined here.
 """

-import json
 import logging
 import os
-import sys
 from dataclasses import dataclass
-from datetime import datetime, timezone
-
-from dotenv import find_dotenv, load_dotenv
-
-# Load .env file, searching current and parent directories (overrides existing env vars)
-load_dotenv(find_dotenv(usecwd=True), override=True)

 logger = logging.getLogger(__name__)

@@ -26,97 +18,31 @@ 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_TIMEOUT = "HINDSIGHT_API_LLM_TIMEOUT"
-ENV_LLM_GROQ_SERVICE_TIER = "HINDSIGHT_API_LLM_GROQ_SERVICE_TIER"
-
-# Per-operation LLM configuration (optional, falls back to global LLM config)
-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_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_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
 ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
 ENV_EMBEDDINGS_TEI_URL = "HINDSIGHT_API_EMBEDDINGS_TEI_URL"
-ENV_EMBEDDINGS_OPENAI_API_KEY = "HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY"
-ENV_EMBEDDINGS_OPENAI_MODEL = "HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL"
-ENV_EMBEDDINGS_OPENAI_BASE_URL = "HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL"
-
-ENV_COHERE_API_KEY = "HINDSIGHT_API_COHERE_API_KEY"
-ENV_EMBEDDINGS_COHERE_MODEL = "HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL"
-ENV_EMBEDDINGS_COHERE_BASE_URL = "HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL"
-ENV_RERANKER_COHERE_MODEL = "HINDSIGHT_API_RERANKER_COHERE_MODEL"
-ENV_RERANKER_COHERE_BASE_URL = "HINDSIGHT_API_RERANKER_COHERE_BASE_URL"
-
-# LiteLLM gateway configuration (for embeddings and reranker via LiteLLM proxy)
-ENV_LITELLM_API_BASE = "HINDSIGHT_API_LITELLM_API_BASE"
-ENV_LITELLM_API_KEY = "HINDSIGHT_API_LITELLM_API_KEY"
-ENV_EMBEDDINGS_LITELLM_MODEL = "HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL"
-ENV_RERANKER_LITELLM_MODEL = "HINDSIGHT_API_RERANKER_LITELLM_MODEL"

 ENV_RERANKER_PROVIDER = "HINDSIGHT_API_RERANKER_PROVIDER"
 ENV_RERANKER_LOCAL_MODEL = "HINDSIGHT_API_RERANKER_LOCAL_MODEL"
-ENV_RERANKER_LOCAL_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"
-ENV_RERANKER_TEI_MAX_CONCURRENT = "HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT"
-ENV_RERANKER_MAX_CANDIDATES = "HINDSIGHT_API_RERANKER_MAX_CANDIDATES"
-ENV_RERANKER_FLASHRANK_MODEL = "HINDSIGHT_API_RERANKER_FLASHRANK_MODEL"
-ENV_RERANKER_FLASHRANK_CACHE_DIR = "HINDSIGHT_API_RERANKER_FLASHRANK_CACHE_DIR"

 ENV_HOST = "HINDSIGHT_API_HOST"
 ENV_PORT = "HINDSIGHT_API_PORT"
 ENV_LOG_LEVEL = "HINDSIGHT_API_LOG_LEVEL"
-ENV_LOG_FORMAT = "HINDSIGHT_API_LOG_FORMAT"
-ENV_WORKERS = "HINDSIGHT_API_WORKERS"
 ENV_MCP_ENABLED = "HINDSIGHT_API_MCP_ENABLED"
 ENV_GRAPH_RETRIEVER = "HINDSIGHT_API_GRAPH_RETRIEVER"
-ENV_MPFP_TOP_K_NEIGHBORS = "HINDSIGHT_API_MPFP_TOP_K_NEIGHBORS"
-ENV_RECALL_MAX_CONCURRENT = "HINDSIGHT_API_RECALL_MAX_CONCURRENT"
-ENV_RECALL_CONNECTION_BUDGET = "HINDSIGHT_API_RECALL_CONNECTION_BUDGET"
 ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
 ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
-ENV_MENTAL_MODEL_REFRESH_CONCURRENCY = "HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY"

 # 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_OBSERVATIONS_ASYNC = "HINDSIGHT_API_RETAIN_OBSERVATIONS_ASYNC"
-
 # Optimization flags
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
 ENV_LAZY_RERANKER = "HINDSIGHT_API_LAZY_RERANKER"

-# Database migrations
-ENV_RUN_MIGRATIONS_ON_STARTUP = "HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP"
-
-# Database connection pool
-ENV_DB_POOL_MIN_SIZE = "HINDSIGHT_API_DB_POOL_MIN_SIZE"
-ENV_DB_POOL_MAX_SIZE = "HINDSIGHT_API_DB_POOL_MAX_SIZE"
-ENV_DB_COMMAND_TIMEOUT = "HINDSIGHT_API_DB_COMMAND_TIMEOUT"
-ENV_DB_ACQUIRE_TIMEOUT = "HINDSIGHT_API_DB_ACQUIRE_TIMEOUT"
-
-# Worker configuration (distributed task processing)
-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"
-
-# Reflect agent settings
-ENV_REFLECT_MAX_ITERATIONS = "HINDSIGHT_API_REFLECT_MAX_ITERATIONS"
-
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
 DEFAULT_LLM_PROVIDER = "openai"
@@ -126,71 +52,21 @@ DEFAULT_LLM_TIMEOUT = 120.0  # seconds

 DEFAULT_EMBEDDINGS_PROVIDER = "local"
 DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"
-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_MAX_CONCURRENT = 4  # Limit concurrent CPU-bound reranking to prevent thrashing
-DEFAULT_RERANKER_TEI_BATCH_SIZE = 128
-DEFAULT_RERANKER_TEI_MAX_CONCURRENT = 8
-DEFAULT_RERANKER_MAX_CANDIDATES = 300
-DEFAULT_RERANKER_FLASHRANK_MODEL = "ms-marco-MiniLM-L-12-v2"  # Best balance of speed and quality
-DEFAULT_RERANKER_FLASHRANK_CACHE_DIR = None  # Use default cache directory
-
-DEFAULT_EMBEDDINGS_COHERE_MODEL = "embed-english-v3.0"
-DEFAULT_RERANKER_COHERE_MODEL = "rerank-english-v3.0"
-
-# LiteLLM defaults
-DEFAULT_LITELLM_API_BASE = "http://localhost:4000"
-DEFAULT_EMBEDDINGS_LITELLM_MODEL = "text-embedding-3-small"
-DEFAULT_RERANKER_LITELLM_MODEL = "cohere/rerank-english-v3.0"

 DEFAULT_HOST = "0.0.0.0"
 DEFAULT_PORT = 8888
 DEFAULT_LOG_LEVEL = "info"
-DEFAULT_LOG_FORMAT = "text"  # Options: "text", "json"
-DEFAULT_WORKERS = 1
 DEFAULT_MCP_ENABLED = True
-DEFAULT_GRAPH_RETRIEVER = "link_expansion"  # Options: "link_expansion", "mpfp", "bfs"
-DEFAULT_MPFP_TOP_K_NEIGHBORS = 20  # Fan-out limit per node in MPFP graph traversal
-DEFAULT_RECALL_MAX_CONCURRENT = 32  # Max concurrent recall operations per worker
-DEFAULT_RECALL_CONNECTION_BUDGET = 4  # Max concurrent DB connections per recall operation
+DEFAULT_GRAPH_RETRIEVER = "bfs"  # Options: "bfs", "mpfp"
 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" or "verbose"
-RETAIN_EXTRACTION_MODES = ("concise", "verbose")  # Allowed extraction modes
-DEFAULT_RETAIN_OBSERVATIONS_ASYNC = False  # Run observation generation async (after retain completes)
-
-# Database migrations
-DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
-
-# Database connection pool
-DEFAULT_DB_POOL_MIN_SIZE = 5
-DEFAULT_DB_POOL_MAX_SIZE = 100
-DEFAULT_DB_COMMAND_TIMEOUT = 60  # seconds
-DEFAULT_DB_ACQUIRE_TIMEOUT = 30  # seconds
-
-# Worker configuration (distributed task processing)
-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
-
-# Reflect agent settings
-DEFAULT_REFLECT_MAX_ITERATIONS = 10  # Max tool call iterations before forcing response
-
 # Default MCP tool descriptions (can be customized via env vars)
 DEFAULT_MCP_RETAIN_DESCRIPTION = """Store important information to long-term memory.

@@ -211,50 +87,8 @@ Use this tool PROACTIVELY to:
 - Remember user's goals and context
 - Personalize responses based on past interactions"""

-# Default embedding dimension (used by initial migration, adjusted at runtime)
-EMBEDDING_DIMENSION = DEFAULT_EMBEDDING_DIMENSION
-
-
-class JsonFormatter(logging.Formatter):
-    """JSON formatter for structured logging.
-
-    Outputs logs in JSON format with a 'severity' field that cloud logging
-    systems (GCP, AWS CloudWatch, etc.) can parse to correctly categorize log levels.
-    """
-
-    SEVERITY_MAP = {
-        logging.DEBUG: "DEBUG",
-        logging.INFO: "INFO",
-        logging.WARNING: "WARNING",
-        logging.ERROR: "ERROR",
-        logging.CRITICAL: "CRITICAL",
-    }
-
-    def format(self, record: logging.LogRecord) -> str:
-        log_entry = {
-            "severity": self.SEVERITY_MAP.get(record.levelno, "DEFAULT"),
-            "message": record.getMessage(),
-            "timestamp": datetime.now(timezone.utc).isoformat(),
-            "logger": record.name,
-        }
-
-        # Add exception info if present
-        if record.exc_info:
-            log_entry["exception"] = self.formatException(record.exc_info)
-
-        return json.dumps(log_entry)
-
-
-def _validate_extraction_mode(mode: str) -> str:
-    """Validate and normalize extraction mode."""
-    mode_lower = mode.lower()
-    if mode_lower not in RETAIN_EXTRACTION_MODES:
-        logger.warning(
-            f"Invalid extraction mode '{mode}', must be one of {RETAIN_EXTRACTION_MODES}. "
-            f"Defaulting to '{DEFAULT_RETAIN_EXTRACTION_MODE}'."
-        )
-        return DEFAULT_RETAIN_EXTRACTION_MODE
-    return mode_lower
+# Required embedding dimension for database schema
+EMBEDDING_DIMENSION = 384


@dataclass
@@ -264,7 +98,7 @@ class HindsightConfig:
    # Database
    database_url: str

-    # LLM (default, used as fallback for per-operation config)
+    # LLM
    llm_provider: str
    llm_api_key: str | None
    llm_model: str
@@ -272,82 +106,33 @@ class HindsightConfig:
    llm_max_concurrent: int
    llm_timeout: float

-    # 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
-
-    reflect_llm_provider: str | None
-    reflect_llm_api_key: str | None
-    reflect_llm_model: str | None
-    reflect_llm_base_url: str | None
-
    # Embeddings
    embeddings_provider: str
    embeddings_local_model: str
    embeddings_tei_url: str | None
-    embeddings_openai_base_url: str | None
-    embeddings_cohere_base_url: str | None

    # Reranker
    reranker_provider: str
    reranker_local_model: str
    reranker_tei_url: str | None
-    reranker_tei_batch_size: int
-    reranker_tei_max_concurrent: int
-    reranker_max_candidates: int
-    reranker_cohere_base_url: str | None

    # Server
    host: str
    port: int
    log_level: str
-    log_format: str
    mcp_enabled: bool

    # Recall
    graph_retriever: str
-    mpfp_top_k_neighbors: int
-    recall_max_concurrent: int
-    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_observations_async: bool
-
    # Optimization flags
    skip_llm_verification: bool
    lazy_reranker: bool

-    # Database migrations
-    run_migrations_on_startup: bool
-
-    # Database connection pool
-    db_pool_min_size: int
-    db_pool_max_size: int
-    db_command_timeout: int
-    db_acquire_timeout: int
-
-    # Worker configuration (distributed task processing)
-    worker_enabled: bool
-    worker_id: str | None
-    worker_poll_interval_ms: int
-    worker_max_retries: int
-    worker_batch_size: int
-    worker_http_port: int
-
-    # Reflect agent settings
-    reflect_max_iterations: int
-
    @classmethod
    def from_env(cls) -> "HindsightConfig":
        """Create configuration from environment variables."""
@@ -361,47 +146,21 @@ class HindsightConfig:
            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_timeout=float(os.getenv(ENV_LLM_TIMEOUT, str(DEFAULT_LLM_TIMEOUT))),
-            # 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 None,
-            retain_llm_base_url=os.getenv(ENV_RETAIN_LLM_BASE_URL) or 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 None,
-            reflect_llm_base_url=os.getenv(ENV_REFLECT_LLM_BASE_URL) or 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_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_tei_url=os.getenv(ENV_RERANKER_TEI_URL),
-            reranker_tei_batch_size=int(os.getenv(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE))),
-            reranker_tei_max_concurrent=int(
-                os.getenv(ENV_RERANKER_TEI_MAX_CONCURRENT, str(DEFAULT_RERANKER_TEI_MAX_CONCURRENT))
-            ),
-            reranker_max_candidates=int(os.getenv(ENV_RERANKER_MAX_CANDIDATES, str(DEFAULT_RERANKER_MAX_CANDIDATES))),
-            reranker_cohere_base_url=os.getenv(ENV_RERANKER_COHERE_BASE_URL) or None,
            # Server
            host=os.getenv(ENV_HOST, DEFAULT_HOST),
            port=int(os.getenv(ENV_PORT, DEFAULT_PORT)),
            log_level=os.getenv(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL),
-            log_format=os.getenv(ENV_LOG_FORMAT, DEFAULT_LOG_FORMAT).lower(),
            mcp_enabled=os.getenv(ENV_MCP_ENABLED, str(DEFAULT_MCP_ENABLED)).lower() == "true",
            # Recall
            graph_retriever=os.getenv(ENV_GRAPH_RETRIEVER, DEFAULT_GRAPH_RETRIEVER),
-            mpfp_top_k_neighbors=int(os.getenv(ENV_MPFP_TOP_K_NEIGHBORS, str(DEFAULT_MPFP_TOP_K_NEIGHBORS))),
-            recall_max_concurrent=int(os.getenv(ENV_RECALL_MAX_CONCURRENT, str(DEFAULT_RECALL_MAX_CONCURRENT))),
-            recall_connection_budget=int(
-                os.getenv(ENV_RECALL_CONNECTION_BUDGET, str(DEFAULT_RECALL_CONNECTION_BUDGET))
-            ),
-            mental_model_refresh_concurrency=int(
-                os.getenv(ENV_MENTAL_MODEL_REFRESH_CONCURRENCY, str(DEFAULT_MENTAL_MODEL_REFRESH_CONCURRENCY))
-            ),
            # Optimization flags
            skip_llm_verification=os.getenv(ENV_SKIP_LLM_VERIFICATION, "false").lower() == "true",
            lazy_reranker=os.getenv(ENV_LAZY_RERANKER, "false").lower() == "true",
@@ -410,38 +169,6 @@ class HindsightConfig:
            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))
-            ),
-            retain_chunk_size=int(os.getenv(ENV_RETAIN_CHUNK_SIZE, str(DEFAULT_RETAIN_CHUNK_SIZE))),
-            retain_extract_causal_links=os.getenv(
-                ENV_RETAIN_EXTRACT_CAUSAL_LINKS, str(DEFAULT_RETAIN_EXTRACT_CAUSAL_LINKS)
-            ).lower()
-            == "true",
-            retain_extraction_mode=_validate_extraction_mode(
-                os.getenv(ENV_RETAIN_EXTRACTION_MODE, DEFAULT_RETAIN_EXTRACTION_MODE)
-            ),
-            retain_observations_async=os.getenv(
-                ENV_RETAIN_OBSERVATIONS_ASYNC, str(DEFAULT_RETAIN_OBSERVATIONS_ASYNC)
-            ).lower()
-            == "true",
-            # Database migrations
-            run_migrations_on_startup=os.getenv(ENV_RUN_MIGRATIONS_ON_STARTUP, "true").lower() == "true",
-            # Database connection pool
-            db_pool_min_size=int(os.getenv(ENV_DB_POOL_MIN_SIZE, str(DEFAULT_DB_POOL_MIN_SIZE))),
-            db_pool_max_size=int(os.getenv(ENV_DB_POOL_MAX_SIZE, str(DEFAULT_DB_POOL_MAX_SIZE))),
-            db_command_timeout=int(os.getenv(ENV_DB_COMMAND_TIMEOUT, str(DEFAULT_DB_COMMAND_TIMEOUT))),
-            db_acquire_timeout=int(os.getenv(ENV_DB_ACQUIRE_TIMEOUT, str(DEFAULT_DB_ACQUIRE_TIMEOUT))),
-            # Worker configuration
-            worker_enabled=os.getenv(ENV_WORKER_ENABLED, str(DEFAULT_WORKER_ENABLED)).lower() == "true",
-            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))),
-            # Reflect agent settings
-            reflect_max_iterations=int(os.getenv(ENV_REFLECT_MAX_ITERATIONS, str(DEFAULT_REFLECT_MAX_ITERATIONS))),
        )

    def get_llm_base_url(self) -> str:
@@ -472,59 +199,22 @@ class HindsightConfig:
        return log_level_map.get(self.log_level.lower(), logging.INFO)

    def configure_logging(self) -> None:
-        """Configure Python logging based on the log level and format.
-
-        When log_format is "json", outputs structured JSON logs with a severity
-        field that GCP Cloud Logging can parse for proper log level categorization.
-        """
-        root_logger = logging.getLogger()
-        root_logger.setLevel(self.get_python_log_level())
-
-        # Remove existing handlers
-        for handler in root_logger.handlers[:]:
-            root_logger.removeHandler(handler)
-
-        # Create handler writing to stdout (GCP treats stderr as ERROR)
-        handler = logging.StreamHandler(sys.stdout)
-        handler.setLevel(self.get_python_log_level())
-
-        if self.log_format == "json":
-            handler.setFormatter(JsonFormatter())
-        else:
-            handler.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(name)s - %(message)s"))
-
-        root_logger.addHandler(handler)
+        """Configure Python logging based on the log level."""
+        logging.basicConfig(
+            level=self.get_python_log_level(),
+            format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+            force=True,  # Override any existing configuration
+        )

    def log_config(self) -> None:
        """Log the current configuration (without sensitive values)."""
        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
-            retain_model = self.retain_llm_model or self.llm_model
-            logger.info(f"LLM (retain): provider={retain_provider}, model={retain_model}")
-        if self.reflect_llm_provider or self.reflect_llm_model:
-            reflect_provider = self.reflect_llm_provider or self.llm_provider
-            reflect_model = self.reflect_llm_model or self.llm_model
-            logger.info(f"LLM (reflect): provider={reflect_provider}, model={reflect_model}")
        logger.info(f"Embeddings: provider={self.embeddings_provider}")
        logger.info(f"Reranker: provider={self.reranker_provider}")
        logger.info(f"Graph retriever: {self.graph_retriever}")


-# Cached config instance
-_config_cache: HindsightConfig | None = None
-
-
 def get_config() -> HindsightConfig:
-    """Get the cached configuration, loading from environment on first call."""
-    global _config_cache
-    if _config_cache is None:
-        _config_cache = HindsightConfig.from_env()
-    return _config_cache
-
-
-def clear_config_cache() -> None:
-    """Clear the config cache. Useful for testing or reloading config."""
-    global _config_cache
-    _config_cache = None
+    """Get the current configuration from environment variables."""
+    return HindsightConfig.from_env()
@@ -6,38 +6,17 @@ Provides an interface for reranking with different backends.
 Configuration via environment variables - see hindsight_api.config for all env var names.
 """

-import asyncio
 import logging
 import os
 from abc import ABC, abstractmethod
-from concurrent.futures import ThreadPoolExecutor

 import httpx

 from ..config import (
-    DEFAULT_LITELLM_API_BASE,
-    DEFAULT_RERANKER_COHERE_MODEL,
-    DEFAULT_RERANKER_FLASHRANK_CACHE_DIR,
-    DEFAULT_RERANKER_FLASHRANK_MODEL,
-    DEFAULT_RERANKER_LITELLM_MODEL,
-    DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT,
    DEFAULT_RERANKER_LOCAL_MODEL,
    DEFAULT_RERANKER_PROVIDER,
-    DEFAULT_RERANKER_TEI_BATCH_SIZE,
-    DEFAULT_RERANKER_TEI_MAX_CONCURRENT,
-    ENV_COHERE_API_KEY,
-    ENV_LITELLM_API_BASE,
-    ENV_LITELLM_API_KEY,
-    ENV_RERANKER_COHERE_BASE_URL,
-    ENV_RERANKER_COHERE_MODEL,
-    ENV_RERANKER_FLASHRANK_CACHE_DIR,
-    ENV_RERANKER_FLASHRANK_MODEL,
-    ENV_RERANKER_LITELLM_MODEL,
-    ENV_RERANKER_LOCAL_MAX_CONCURRENT,
    ENV_RERANKER_LOCAL_MODEL,
    ENV_RERANKER_PROVIDER,
-    ENV_RERANKER_TEI_BATCH_SIZE,
-    ENV_RERANKER_TEI_MAX_CONCURRENT,
    ENV_RERANKER_TEI_URL,
 )

@@ -68,7 +47,7 @@ class CrossEncoderModel(ABC):
        pass

    @abstractmethod
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
+    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
        """
        Score query-document pairs for relevance.

@@ -91,34 +70,25 @@ class LocalSTCrossEncoder(CrossEncoderModel):
    - Fast inference (~80ms for 100 pairs on CPU)
    - Small model (80MB)
    - Trained for passage re-ranking
-
-    Uses a dedicated thread pool to limit concurrent CPU-bound work.
    """

-    # Shared executor across all instances (one model loaded anyway)
-    _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):
+    def __init__(self, model_name: str | None = None):
        """
        Initialize local SentenceTransformers cross-encoder.

        Args:
            model_name: Name of the CrossEncoder model to use.
                       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.
        """
        self.model_name = model_name or DEFAULT_RERANKER_LOCAL_MODEL
        self._model = None
-        LocalSTCrossEncoder._max_concurrent = max_concurrent

    @property
    def provider_name(self) -> str:
        return "local"

    async def initialize(self) -> None:
-        """Load the cross-encoder model and initialize the executor."""
+        """Load the cross-encoder model."""
        if self._model is not None:
            return

@@ -130,30 +100,14 @@ class LocalSTCrossEncoder(CrossEncoderModel):
                "Install it with: pip install sentence-transformers"
            )

-        # Note: We use CPU even when GPU/MPS is available because:
-        # 1. The reranker model (MiniLM) is tiny (~22M params)
-        # 2. Batch sizes are small (~100-200 pairs)
-        # 3. Data transfer overhead to GPU outweighs compute benefit
-        # 4. CPU inference is actually faster for this workload
        logger.info(f"Reranker: initializing local provider with model {self.model_name}")
        self._model = CrossEncoder(self.model_name)
+        logger.info("Reranker: local provider initialized")

-        # Initialize shared executor (limited workers naturally limits concurrency)
-        if LocalSTCrossEncoder._executor is None:
-            LocalSTCrossEncoder._executor = ThreadPoolExecutor(
-                max_workers=LocalSTCrossEncoder._max_concurrent,
-                thread_name_prefix="reranker",
-            )
-            logger.info(f"Reranker: local provider initialized (max_concurrent={LocalSTCrossEncoder._max_concurrent})")
-        else:
-            logger.info("Reranker: local provider initialized (using existing executor)")
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
+    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
        """
        Score query-document pairs for relevance.

-        Uses a dedicated thread pool with limited workers to prevent CPU thrashing.
-
        Args:
            pairs: List of (query, document) tuples to score

@@ -162,13 +116,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
        """
        if self._model is None:
            raise RuntimeError("Reranker not initialized. Call initialize() first.")
-
-        # Use dedicated executor - limited workers naturally limits concurrency
-        loop = asyncio.get_event_loop()
-        scores = await loop.run_in_executor(
-            LocalSTCrossEncoder._executor,
-            lambda: self._model.predict(pairs, show_progress_bar=False),
-        )
+        scores = self._model.predict(pairs, show_progress_bar=False)
        return scores.tolist() if hasattr(scores, "tolist") else list(scores)


@@ -180,21 +128,13 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
    See: https://github.com/huggingface/text-embeddings-inference

    Note: The TEI server must be running a cross-encoder/reranker model.
-
-    Requests are made in parallel with configurable batch size and max concurrency (backpressure).
-    Uses a GLOBAL semaphore to limit concurrent requests across ALL recall operations.
    """

-    # Global semaphore shared across all instances and calls to prevent thundering herd
-    _global_semaphore: asyncio.Semaphore | None = None
-    _global_max_concurrent: int = DEFAULT_RERANKER_TEI_MAX_CONCURRENT
-
    def __init__(
        self,
        base_url: str,
        timeout: float = 30.0,
-        batch_size: int = DEFAULT_RERANKER_TEI_BATCH_SIZE,
-        max_concurrent: int = DEFAULT_RERANKER_TEI_MAX_CONCURRENT,
+        batch_size: int = 32,
        max_retries: int = 3,
        retry_delay: float = 0.5,
    ):
@@ -204,246 +144,80 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
        Args:
            base_url: Base URL of the TEI server (e.g., "http://localhost:8080")
            timeout: Request timeout in seconds (default: 30.0)
-            batch_size: Maximum batch size for rerank requests (default: 128)
-            max_concurrent: Maximum concurrent requests for backpressure (default: 8).
-                           This is a GLOBAL limit across all parallel recall operations.
+            batch_size: Maximum batch size for rerank requests (default: 32)
            max_retries: Maximum number of retries for failed requests (default: 3)
            retry_delay: Initial delay between retries in seconds, doubles each retry (default: 0.5)
        """
        self.base_url = base_url.rstrip("/")
        self.timeout = timeout
        self.batch_size = batch_size
-        self.max_concurrent = max_concurrent
        self.max_retries = max_retries
        self.retry_delay = retry_delay
-        self._async_client: httpx.AsyncClient | None = None
+        self._client: httpx.Client | None = None
        self._model_id: str | None = None

-        # Update global semaphore if max_concurrent changed
-        if (
-            RemoteTEICrossEncoder._global_semaphore is None
-            or RemoteTEICrossEncoder._global_max_concurrent != max_concurrent
-        ):
-            RemoteTEICrossEncoder._global_max_concurrent = max_concurrent
-            RemoteTEICrossEncoder._global_semaphore = asyncio.Semaphore(max_concurrent)
-
    @property
    def provider_name(self) -> str:
        return "tei"

-    async def _async_request_with_retry(
-        self,
-        client: httpx.AsyncClient,
-        semaphore: asyncio.Semaphore,
-        method: str,
-        url: str,
-        **kwargs,
-    ) -> httpx.Response:
-        """Make an async HTTP request with automatic retries on transient errors and semaphore for backpressure."""
+    def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
+        """Make an HTTP request with automatic retries on transient errors."""
+        import time
+
        last_error = None
        delay = self.retry_delay

-        async with semaphore:
-            for attempt in range(self.max_retries + 1):
-                try:
-                    if method == "GET":
-                        response = await client.get(url, **kwargs)
-                    else:
-                        response = await client.post(url, **kwargs)
-                    response.raise_for_status()
-                    return response
-                except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as e:
+        for attempt in range(self.max_retries + 1):
+            try:
+                if method == "GET":
+                    response = self._client.get(url, **kwargs)
+                else:
+                    response = self._client.post(url, **kwargs)
+                response.raise_for_status()
+                return response
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    logger.warning(
+                        f"TEI request failed (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s..."
+                    )
+                    time.sleep(delay)
+                    delay *= 2  # Exponential backoff
+            except httpx.HTTPStatusError as e:
+                # Retry on 5xx server errors
+                if e.response.status_code >= 500 and attempt < self.max_retries:
                    last_error = e
-                    if attempt < self.max_retries:
-                        logger.warning(
-                            f"TEI request failed (attempt {attempt + 1}/{self.max_retries + 1}): {e}. "
-                            f"Retrying in {delay}s..."
-                        )
-                        await asyncio.sleep(delay)
-                        delay *= 2  # Exponential backoff
-                except httpx.HTTPStatusError as e:
-                    # Retry on 5xx server errors
-                    if e.response.status_code >= 500 and attempt < self.max_retries:
-                        last_error = e
-                        logger.warning(
-                            f"TEI server error (attempt {attempt + 1}/{self.max_retries + 1}): {e}. "
-                            f"Retrying in {delay}s..."
-                        )
-                        await asyncio.sleep(delay)
-                        delay *= 2
-                    else:
-                        raise
+                    logger.warning(
+                        f"TEI server error (attempt {attempt + 1}/{self.max_retries + 1}): {e}. Retrying in {delay}s..."
+                    )
+                    time.sleep(delay)
+                    delay *= 2
+                else:
+                    raise

        raise last_error

    async def initialize(self) -> None:
        """Initialize the HTTP client and verify server connectivity."""
-        if self._async_client is not None:
+        if self._client is not None:
            return

-        logger.info(
-            f"Reranker: initializing TEI provider at {self.base_url} "
-            f"(batch_size={self.batch_size}, max_concurrent={self.max_concurrent})"
-        )
-        self._async_client = httpx.AsyncClient(timeout=self.timeout)
+        logger.info(f"Reranker: initializing TEI provider at {self.base_url}")
+        self._client = httpx.Client(timeout=self.timeout)

        # Verify server is reachable and get model info
-        # Use a temporary semaphore for initialization
-        init_semaphore = asyncio.Semaphore(1)
        try:
-            response = await self._async_request_with_retry(
-                self._async_client, init_semaphore, "GET", f"{self.base_url}/info"
-            )
+            response = self._request_with_retry("GET", f"{self.base_url}/info")
            info = response.json()
            self._model_id = info.get("model_id", "unknown")
            logger.info(f"Reranker: TEI provider initialized (model: {self._model_id})")
        except httpx.HTTPError as e:
-            self._async_client = None
            raise RuntimeError(f"Failed to connect to TEI server at {self.base_url}: {e}")

-    async def _rerank_query_group(
-        self,
-        client: httpx.AsyncClient,
-        semaphore: asyncio.Semaphore,
-        query: str,
-        texts: list[str],
-    ) -> list[tuple[int, float]]:
-        """Rerank a single query group and return list of (original_index, score) tuples."""
-        try:
-            response = await self._async_request_with_retry(
-                client,
-                semaphore,
-                "POST",
-                f"{self.base_url}/rerank",
-                json={
-                    "query": query,
-                    "texts": texts,
-                    "return_text": False,
-                },
-            )
-            results = response.json()
-            # TEI returns results sorted by score descending, with original index
-            return [(result["index"], result["score"]) for result in results]
-        except httpx.HTTPError as e:
-            raise RuntimeError(f"TEI rerank request failed: {e}")
-
-    async def _predict_async(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """Async implementation of predict that runs requests in parallel with backpressure."""
-        if not pairs:
-            return []
-
-        # Group all pairs by query
-        query_groups: dict[str, list[tuple[int, str]]] = {}
-        for idx, (query, text) in enumerate(pairs):
-            if query not in query_groups:
-                query_groups[query] = []
-            query_groups[query].append((idx, text))
-
-        # Split each query group into batches
-        tasks_info: list[tuple[str, list[int], list[str]]] = []  # (query, indices, texts)
-        for query, indexed_texts in query_groups.items():
-            indices = [idx for idx, _ in indexed_texts]
-            texts = [text for _, text in indexed_texts]
-
-            # Split into batches
-            for i in range(0, len(texts), self.batch_size):
-                batch_indices = indices[i : i + self.batch_size]
-                batch_texts = texts[i : i + self.batch_size]
-                tasks_info.append((query, batch_indices, batch_texts))
-
-        # Run all requests in parallel with GLOBAL semaphore for backpressure
-        # This ensures max_concurrent is respected across ALL parallel recall operations
-        all_scores = [0.0] * len(pairs)
-        semaphore = RemoteTEICrossEncoder._global_semaphore
-
-        tasks = [
-            self._rerank_query_group(self._async_client, semaphore, query, texts) for query, _, texts in tasks_info
-        ]
-        results = await asyncio.gather(*tasks)
-
-        # Map scores back to original positions
-        for (_, indices, _), result_scores in zip(tasks_info, results):
-            for original_idx_in_batch, score in result_scores:
-                global_idx = indices[original_idx_in_batch]
-                all_scores[global_idx] = score
-
-        return all_scores
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
+    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
        """
        Score query-document pairs using the remote TEI reranker.

-        Requests are made in parallel with configurable backpressure.
-
-        Args:
-            pairs: List of (query, document) tuples to score
-
-        Returns:
-            List of relevance scores
-        """
-        if self._async_client is None:
-            raise RuntimeError("Reranker not initialized. Call initialize() first.")
-
-        return await self._predict_async(pairs)
-
-
-class CohereCrossEncoder(CrossEncoderModel):
-    """
-    Cohere cross-encoder implementation using the Cohere Rerank API.
-
-    Supports rerank-english-v3.0 and rerank-multilingual-v3.0 models.
-    """
-
-    def __init__(
-        self,
-        api_key: str,
-        model: str = DEFAULT_RERANKER_COHERE_MODEL,
-        base_url: str | None = None,
-        timeout: float = 60.0,
-    ):
-        """
-        Initialize Cohere cross-encoder client.
-
-        Args:
-            api_key: Cohere API key
-            model: Cohere rerank model name (default: rerank-english-v3.0)
-            base_url: Custom base URL for Cohere-compatible API (e.g., Azure-hosted endpoint)
-            timeout: Request timeout in seconds (default: 60.0)
-        """
-        self.api_key = api_key
-        self.model = model
-        self.base_url = base_url
-        self.timeout = timeout
-        self._client = None
-
-    @property
-    def provider_name(self) -> str:
-        return "cohere"
-
-    async def initialize(self) -> None:
-        """Initialize the Cohere client."""
-        if self._client is not None:
-            return
-
-        try:
-            import cohere
-        except ImportError:
-            raise ImportError("cohere is required for CohereCrossEncoder. Install it with: pip install cohere")
-
-        base_url_msg = f" at {self.base_url}" if self.base_url else ""
-        logger.info(f"Reranker: initializing Cohere provider with model {self.model}{base_url_msg}")
-
-        # Build client kwargs, only including base_url if set (for Azure or custom endpoints)
-        client_kwargs = {"api_key": self.api_key, "timeout": self.timeout}
-        if self.base_url:
-            client_kwargs["base_url"] = self.base_url
-        self._client = cohere.Client(**client_kwargs)
-        logger.info("Reranker: Cohere provider initialized")
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """
-        Score query-document pairs using the Cohere Rerank API.
-
        Args:
            pairs: List of (query, document) tuples to score

@@ -456,312 +230,50 @@ class CohereCrossEncoder(CrossEncoderModel):
        if not pairs:
            return []

-        # Run sync Cohere API calls in thread pool
-        loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(None, self._predict_sync, pairs)
+        all_scores = []

-    def _predict_sync(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """Synchronous predict implementation for Cohere API."""
-        # Group pairs by query for efficient batching
-        # Cohere rerank expects one query with multiple documents
-        query_groups: dict[str, list[tuple[int, str]]] = {}
-        for idx, (query, text) in enumerate(pairs):
-            if query not in query_groups:
-                query_groups[query] = []
-            query_groups[query].append((idx, text))
+        # Process in batches
+        for i in range(0, len(pairs), self.batch_size):
+            batch = pairs[i : i + self.batch_size]

-        all_scores = [0.0] * len(pairs)
+            # TEI rerank endpoint expects query and texts separately
+            # All pairs in a batch should have the same query for optimal performance
+            # but we handle mixed queries by making separate requests per unique query
+            query_groups: dict[str, list[tuple[int, str]]] = {}
+            for idx, (query, text) in enumerate(batch):
+                if query not in query_groups:
+                    query_groups[query] = []
+                query_groups[query].append((idx, text))

-        for query, indexed_texts in query_groups.items():
-            texts = [text for _, text in indexed_texts]
-            indices = [idx for idx, _ in indexed_texts]
+            batch_scores = [0.0] * len(batch)

-            response = self._client.rerank(
-                query=query,
-                documents=texts,
-                model=self.model,
-                return_documents=False,
-            )
+            for query, indexed_texts in query_groups.items():
+                texts = [text for _, text in indexed_texts]
+                indices = [idx for idx, _ in indexed_texts]

-            # Map scores back to original positions
-            for result in response.results:
-                original_idx = result.index
-                score = result.relevance_score
-                all_scores[indices[original_idx]] = score
+                try:
+                    response = self._request_with_retry(
+                        "POST",
+                        f"{self.base_url}/rerank",
+                        json={
+                            "query": query,
+                            "texts": texts,
+                            "return_text": False,
+                        },
+                    )
+                    results = response.json()

-        return all_scores
+                    # TEI returns results sorted by score descending, with original index
+                    for result in results:
+                        original_idx = result["index"]
+                        score = result["score"]
+                        # Map back to batch position
+                        batch_scores[indices[original_idx]] = score

+                except httpx.HTTPError as e:
+                    raise RuntimeError(f"TEI rerank request failed: {e}")

-class RRFPassthroughCrossEncoder(CrossEncoderModel):
-    """
-    Passthrough cross-encoder that preserves RRF scores without neural reranking.
-
-    This is useful for:
-    - Testing retrieval quality without reranking overhead
-    - Deployments where reranking latency is unacceptable
-    - Debugging to isolate retrieval vs reranking issues
-    """
-
-    def __init__(self):
-        """Initialize RRF passthrough cross-encoder."""
-        pass
-
-    @property
-    def provider_name(self) -> str:
-        return "rrf"
-
-    async def initialize(self) -> None:
-        """No initialization needed."""
-        logger.info("Reranker: RRF passthrough provider initialized (neural reranking disabled)")
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """
-        Return neutral scores - actual ranking uses RRF scores from retrieval.
-
-        Args:
-            pairs: List of (query, document) tuples (ignored)
-
-        Returns:
-            List of 0.5 scores (neutral, lets RRF scores dominate)
-        """
-        # Return neutral scores so RRF ranking is preserved
-        return [0.5] * len(pairs)
-
-
-class FlashRankCrossEncoder(CrossEncoderModel):
-    """
-    FlashRank cross-encoder implementation.
-
-    FlashRank is an ultra-lite reranking library that runs on CPU without
-    requiring PyTorch or Transformers. It's ideal for serverless deployments
-    with minimal cold-start overhead.
-
-    Available models:
-    - ms-marco-TinyBERT-L-2-v2: Fastest, ~4MB
-    - ms-marco-MiniLM-L-12-v2: Best quality, ~34MB (default)
-    - rank-T5-flan: Best zero-shot, ~110MB
-    - ms-marco-MultiBERT-L-12: Multi-lingual, ~150MB
-    """
-
-    # Shared executor for CPU-bound reranking
-    _executor: ThreadPoolExecutor | None = None
-    _max_concurrent: int = 4
-
-    def __init__(
-        self,
-        model_name: str | None = None,
-        cache_dir: str | None = None,
-        max_length: int = 512,
-        max_concurrent: int = 4,
-    ):
-        """
-        Initialize FlashRank cross-encoder.
-
-        Args:
-            model_name: FlashRank model name. Default: ms-marco-MiniLM-L-12-v2
-            cache_dir: Directory to cache downloaded models. Default: system cache
-            max_length: Maximum sequence length for reranking. Default: 512
-            max_concurrent: Maximum concurrent reranking calls. Default: 4
-        """
-        self.model_name = model_name or DEFAULT_RERANKER_FLASHRANK_MODEL
-        self.cache_dir = cache_dir or DEFAULT_RERANKER_FLASHRANK_CACHE_DIR
-        self.max_length = max_length
-        self._ranker = None
-        FlashRankCrossEncoder._max_concurrent = max_concurrent
-
-    @property
-    def provider_name(self) -> str:
-        return "flashrank"
-
-    async def initialize(self) -> None:
-        """Load the FlashRank model."""
-        if self._ranker is not None:
-            return
-
-        try:
-            from flashrank import Ranker  # type: ignore[import-untyped]
-        except ImportError:
-            raise ImportError("flashrank is required for FlashRankCrossEncoder. Install it with: pip install flashrank")
-
-        logger.info(f"Reranker: initializing FlashRank provider with model {self.model_name}")
-
-        # Initialize ranker with optional cache directory
-        ranker_kwargs = {"model_name": self.model_name, "max_length": self.max_length}
-        if self.cache_dir:
-            ranker_kwargs["cache_dir"] = self.cache_dir
-
-        self._ranker = Ranker(**ranker_kwargs)
-
-        # Initialize shared executor
-        if FlashRankCrossEncoder._executor is None:
-            FlashRankCrossEncoder._executor = ThreadPoolExecutor(
-                max_workers=FlashRankCrossEncoder._max_concurrent,
-                thread_name_prefix="flashrank",
-            )
-            logger.info(
-                f"Reranker: FlashRank provider initialized (max_concurrent={FlashRankCrossEncoder._max_concurrent})"
-            )
-        else:
-            logger.info("Reranker: FlashRank provider initialized (using existing executor)")
-
-    def _predict_sync(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """Synchronous predict - processes each query group."""
-        from flashrank import RerankRequest  # type: ignore[import-untyped]
-
-        if not pairs:
-            return []
-
-        # Group pairs by query
-        query_groups: dict[str, list[tuple[int, str]]] = {}
-        for idx, (query, text) in enumerate(pairs):
-            if query not in query_groups:
-                query_groups[query] = []
-            query_groups[query].append((idx, text))
-
-        all_scores = [0.0] * len(pairs)
-
-        for query, indexed_texts in query_groups.items():
-            # Build passages list for FlashRank
-            passages = [{"id": i, "text": text} for i, (_, text) in enumerate(indexed_texts)]
-            global_indices = [idx for idx, _ in indexed_texts]
-
-            # Create rerank request
-            request = RerankRequest(query=query, passages=passages)
-            results = self._ranker.rerank(request)
-
-            # Map scores back to original positions
-            for result in results:
-                local_idx = result["id"]
-                score = result["score"]
-                global_idx = global_indices[local_idx]
-                all_scores[global_idx] = score
-
-        return all_scores
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """
-        Score query-document pairs using FlashRank.
-
-        Args:
-            pairs: List of (query, document) tuples to score
-
-        Returns:
-            List of relevance scores (higher = more relevant)
-        """
-        if self._ranker is None:
-            raise RuntimeError("Reranker not initialized. Call initialize() first.")
-
-        # Run in thread pool to avoid blocking event loop
-        loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(FlashRankCrossEncoder._executor, self._predict_sync, pairs)
-
-
-class LiteLLMCrossEncoder(CrossEncoderModel):
-    """
-    LiteLLM cross-encoder implementation using LiteLLM proxy's /rerank endpoint.
-
-    LiteLLM provides a unified interface for multiple reranking providers via
-    the Cohere-compatible /rerank endpoint.
-    See: https://docs.litellm.ai/docs/rerank
-
-    Supported providers via LiteLLM:
-    - Cohere (rerank-english-v3.0, etc.) - prefix with cohere/
-    - Together AI - prefix with together_ai/
-    - Azure AI - prefix with azure_ai/
-    - Jina AI - prefix with jina_ai/
-    - AWS Bedrock - prefix with bedrock/
-    - Voyage AI - prefix with voyage/
-    """
-
-    def __init__(
-        self,
-        api_base: str = DEFAULT_LITELLM_API_BASE,
-        api_key: str | None = None,
-        model: str = DEFAULT_RERANKER_LITELLM_MODEL,
-        timeout: float = 60.0,
-    ):
-        """
-        Initialize LiteLLM cross-encoder client.
-
-        Args:
-            api_base: Base URL of the LiteLLM proxy (default: http://localhost:4000)
-            api_key: API key for the LiteLLM proxy (optional, depends on proxy config)
-            model: Reranking model name (default: cohere/rerank-english-v3.0)
-                   Use provider prefix (e.g., cohere/, together_ai/, voyage/)
-            timeout: Request timeout in seconds (default: 60.0)
-        """
-        self.api_base = api_base.rstrip("/")
-        self.api_key = api_key
-        self.model = model
-        self.timeout = timeout
-        self._async_client: httpx.AsyncClient | None = None
-
-    @property
-    def provider_name(self) -> str:
-        return "litellm"
-
-    async def initialize(self) -> None:
-        """Initialize the async HTTP client."""
-        if self._async_client is not None:
-            return
-
-        logger.info(f"Reranker: initializing LiteLLM provider at {self.api_base} with model {self.model}")
-
-        headers = {"Content-Type": "application/json"}
-        if self.api_key:
-            headers["Authorization"] = f"Bearer {self.api_key}"
-
-        self._async_client = httpx.AsyncClient(timeout=self.timeout, headers=headers)
-        logger.info("Reranker: LiteLLM provider initialized")
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """
-        Score query-document pairs using the LiteLLM proxy's /rerank endpoint.
-
-        Args:
-            pairs: List of (query, document) tuples to score
-
-        Returns:
-            List of relevance scores
-        """
-        if self._async_client is None:
-            raise RuntimeError("Reranker not initialized. Call initialize() first.")
-
-        if not pairs:
-            return []
-
-        # Group pairs by query (LiteLLM rerank expects one query with multiple documents)
-        query_groups: dict[str, list[tuple[int, str]]] = {}
-        for idx, (query, text) in enumerate(pairs):
-            if query not in query_groups:
-                query_groups[query] = []
-            query_groups[query].append((idx, text))
-
-        all_scores = [0.0] * len(pairs)
-
-        for query, indexed_texts in query_groups.items():
-            texts = [text for _, text in indexed_texts]
-            indices = [idx for idx, _ in indexed_texts]
-
-            # LiteLLM /rerank follows Cohere API format
-            response = await self._async_client.post(
-                f"{self.api_base}/rerank",
-                json={
-                    "model": self.model,
-                    "query": query,
-                    "documents": texts,
-                    "top_n": len(texts),  # Return all scores
-                },
-            )
-            response.raise_for_status()
-            result = response.json()
-
-            # Map scores back to original positions
-            # Response format: {"results": [{"index": 0, "relevance_score": 0.9}, ...]}
-            for item in result.get("results", []):
-                original_idx = item["index"]
-                score = item.get("relevance_score", item.get("score", 0.0))
-                all_scores[indices[original_idx]] = score
+            all_scores.extend(batch_scores)

        return all_scores

@@ -781,35 +293,10 @@ def create_cross_encoder_from_env() -> CrossEncoderModel:
        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'")
-        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)
+        return RemoteTEICrossEncoder(base_url=url)
    elif provider == "local":
        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:
-            raise ValueError(f"{ENV_COHERE_API_KEY} is required when {ENV_RERANKER_PROVIDER} is 'cohere'")
-        model = os.environ.get(ENV_RERANKER_COHERE_MODEL, DEFAULT_RERANKER_COHERE_MODEL)
-        base_url = os.environ.get(ENV_RERANKER_COHERE_BASE_URL) or None
-        return CohereCrossEncoder(api_key=api_key, model=model, base_url=base_url)
-    elif provider == "flashrank":
-        model = os.environ.get(ENV_RERANKER_FLASHRANK_MODEL, DEFAULT_RERANKER_FLASHRANK_MODEL)
-        cache_dir = os.environ.get(ENV_RERANKER_FLASHRANK_CACHE_DIR, DEFAULT_RERANKER_FLASHRANK_CACHE_DIR)
-        return FlashRankCrossEncoder(model_name=model, cache_dir=cache_dir)
-    elif provider == "litellm":
-        api_base = os.environ.get(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE)
-        api_key = os.environ.get(ENV_LITELLM_API_KEY)
-        model = os.environ.get(ENV_RERANKER_LITELLM_MODEL, DEFAULT_RERANKER_LITELLM_MODEL)
-        return LiteLLMCrossEncoder(api_base=api_base, api_key=api_key, model=model)
-    elif provider == "rrf":
-        return RRFPassthroughCrossEncoder()
+        return LocalSTCrossEncoder(model_name=model_name)
    else:
-        raise ValueError(
-            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei', 'cohere', 'flashrank', 'litellm', 'rrf'"
-        )
+        raise ValueError(f"Unknown reranker provider: {provider}. Supported: 'local', 'tei'")
@@ -1,284 +0,0 @@
-"""
-Database connection budget management.
-
-Limits concurrent database connections per operation to prevent
-a single operation (e.g., recall with parallel queries) from
-exhausting the connection pool.
-"""
-
-import asyncio
-import logging
-import uuid
-from contextlib import asynccontextmanager
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, AsyncIterator
-
-if TYPE_CHECKING:
-    import asyncpg
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class OperationBudget:
-    """
-    Tracks connection budget for a single operation.
-
-    Each operation gets a semaphore limiting its concurrent connections.
-    """
-
-    operation_id: str
-    max_connections: int
-    semaphore: asyncio.Semaphore = field(init=False)
-    active_count: int = field(default=0, init=False)
-
-    def __post_init__(self):
-        self.semaphore = asyncio.Semaphore(self.max_connections)
-
-
-class ConnectionBudgetManager:
-    """
-    Manages per-operation connection budgets.
-
-    Usage:
-        manager = ConnectionBudgetManager(default_budget=4)
-
-        # Start an operation
-        async with manager.operation(max_connections=2) as op:
-            # Acquire connections within the budget
-            async with op.acquire(pool) as conn:
-                await conn.fetch(...)
-
-            # Multiple connections respect the budget
-            async with op.acquire(pool) as conn1, op.acquire(pool) as conn2:
-                # At most 2 concurrent connections for this operation
-                ...
-    """
-
-    def __init__(self, default_budget: int = 4):
-        """
-        Initialize the budget manager.
-
-        Args:
-            default_budget: Default max connections per operation
-        """
-        self.default_budget = default_budget
-        self._operations: dict[str, OperationBudget] = {}
-        self._lock = asyncio.Lock()
-
-    @asynccontextmanager
-    async def operation(
-        self,
-        max_connections: int | None = None,
-        operation_id: str | None = None,
-    ) -> AsyncIterator["BudgetedOperation"]:
-        """
-        Create a budgeted operation context.
-
-        Args:
-            max_connections: Max concurrent connections for this operation.
-                           Defaults to manager's default_budget.
-            operation_id: Optional custom operation ID. Auto-generated if not provided.
-
-        Yields:
-            BudgetedOperation context for acquiring connections
-        """
-        op_id = operation_id or f"op-{uuid.uuid4().hex[:12]}"
-        budget = max_connections or self.default_budget
-
-        async with self._lock:
-            if op_id in self._operations:
-                raise ValueError(f"Operation {op_id} already exists")
-            self._operations[op_id] = OperationBudget(op_id, budget)
-
-        try:
-            yield BudgetedOperation(self, op_id)
-        finally:
-            async with self._lock:
-                self._operations.pop(op_id, None)
-
-    def _get_budget(self, operation_id: str) -> OperationBudget:
-        """Get budget for an operation (internal use)."""
-        budget = self._operations.get(operation_id)
-        if not budget:
-            raise ValueError(f"Operation {operation_id} not found")
-        return budget
-
-
-class BudgetedOperation:
-    """
-    A single operation with connection budget.
-
-    Provides methods to acquire connections within the budget.
-    """
-
-    def __init__(self, manager: ConnectionBudgetManager, operation_id: str):
-        self._manager = manager
-        self.operation_id = operation_id
-
-    @property
-    def budget(self) -> OperationBudget:
-        """Get the budget for this operation."""
-        return self._manager._get_budget(self.operation_id)
-
-    @asynccontextmanager
-    async def acquire(self, pool: "asyncpg.Pool") -> AsyncIterator["asyncpg.Connection"]:
-        """
-        Acquire a connection within the operation's budget.
-
-        Blocks if the operation has reached its connection limit.
-
-        Args:
-            pool: asyncpg connection pool
-
-        Yields:
-            Database connection
-        """
-        budget = self.budget
-        async with budget.semaphore:
-            budget.active_count += 1
-            conn = await pool.acquire()
-            try:
-                yield conn
-            finally:
-                budget.active_count -= 1
-                await pool.release(conn)
-
-    def wrap_pool(self, pool: "asyncpg.Pool") -> "BudgetedPool":
-        """
-        Wrap a pool with this operation's budget.
-
-        The returned BudgetedPool can be passed to functions expecting a pool,
-        and all acquire() calls will be limited by this operation's budget.
-
-        Args:
-            pool: asyncpg connection pool to wrap
-
-        Returns:
-            BudgetedPool that limits connections to this operation's budget
-        """
-        return BudgetedPool(pool, self)
-
-    async def acquire_many(
-        self,
-        pool: "asyncpg.Pool",
-        count: int,
-    ) -> AsyncIterator[list["asyncpg.Connection"]]:
-        """
-        Acquire multiple connections within the budget.
-
-        Note: This acquires connections sequentially to respect the budget.
-        For parallel acquisition, use multiple acquire() calls with asyncio.gather().
-
-        Args:
-            pool: asyncpg connection pool
-            count: Number of connections to acquire
-
-        Yields:
-            List of database connections
-        """
-        connections = []
-        try:
-            for _ in range(count):
-                conn = await pool.acquire()
-                connections.append(conn)
-            yield connections
-        finally:
-            for conn in connections:
-                await pool.release(conn)
-
-
-# Global default manager instance
-_default_manager: ConnectionBudgetManager | None = None
-
-
-def get_budget_manager(default_budget: int = 4) -> ConnectionBudgetManager:
-    """
-    Get or create the global budget manager.
-
-    Args:
-        default_budget: Default max connections per operation
-
-    Returns:
-        Global ConnectionBudgetManager instance
-    """
-    global _default_manager
-    if _default_manager is None:
-        _default_manager = ConnectionBudgetManager(default_budget=default_budget)
-    return _default_manager
-
-
-@asynccontextmanager
-async def budgeted_operation(
-    max_connections: int | None = None,
-    operation_id: str | None = None,
-    default_budget: int = 4,
-) -> AsyncIterator[BudgetedOperation]:
-    """
-    Convenience function to create a budgeted operation.
-
-    Args:
-        max_connections: Max concurrent connections for this operation
-        operation_id: Optional custom operation ID
-        default_budget: Default budget if manager not yet created
-
-    Yields:
-        BudgetedOperation context
-
-    Example:
-        async with budgeted_operation(max_connections=2) as op:
-            async with op.acquire(pool) as conn:
-                await conn.fetch(...)
-    """
-    manager = get_budget_manager(default_budget)
-    async with manager.operation(max_connections, operation_id) as op:
-        yield op
-
-
-class BudgetedPool:
-    """
-    A pool wrapper that limits concurrent connection acquisitions.
-
-    This can be passed to functions expecting a pool, and acquire()
-    calls will be limited by the budget semaphore.
-
-    Usage:
-        async with budgeted_operation(max_connections=4) as op:
-            budgeted_pool = op.wrap_pool(pool)
-            # Pass budgeted_pool to functions that expect a pool
-            await some_function(budgeted_pool, ...)
-    """
-
-    def __init__(self, pool: "asyncpg.Pool", operation: BudgetedOperation):
-        self._pool = pool
-        self._operation = operation
-
-    async def acquire(self) -> "asyncpg.Connection":
-        """
-        Acquire a connection within the budget.
-
-        Note: Caller must release the connection when done.
-        Prefer using as context manager via acquire_with_retry or op.acquire().
-        """
-        budget = self._operation.budget
-        await budget.semaphore.acquire()
-        budget.active_count += 1
-        try:
-            return await self._pool.acquire()
-        except Exception:
-            budget.active_count -= 1
-            budget.semaphore.release()
-            raise
-
-    async def release(self, conn: "asyncpg.Connection") -> None:
-        """Release a connection back to the pool."""
-        budget = self._operation.budget
-        try:
-            await self._pool.release(conn)
-        finally:
-            budget.active_count -= 1
-            budget.semaphore.release()
-
-    def __getattr__(self, name):
-        """Proxy other attributes to the underlying pool."""
-        return getattr(self._pool, name)
@@ -83,22 +83,11 @@ async def acquire_with_retry(pool: asyncpg.Pool, max_retries: int = DEFAULT_MAX_
    Yields:
        An asyncpg connection
    """
-    import time
-
-    start = time.time()

    async def acquire():
        return await pool.acquire()

    conn = await retry_with_backoff(acquire, max_retries=max_retries)
-    acquire_time = time.time() - start
-
-    # Log slow connection acquisitions (indicates pool contention)
-    if acquire_time > 0.05:  # 50ms threshold
-        pool_size = pool.get_size()
-        pool_free = pool.get_idle_size()
-        logger.warning(f"[DB POOL] Slow acquire: {acquire_time:.3f}s | size={pool_size}, idle={pool_free}")
-
    try:
        yield conn
    finally:
@@ -3,8 +3,8 @@ Embeddings abstraction for the memory system.

 Provides an interface for generating embeddings with different backends.

-The embedding dimension is auto-detected from the model at initialization.
-The database schema is automatically adjusted to match the model's dimension.
+IMPORTANT: All embeddings must produce 384-dimensional vectors to match
+the database schema (pgvector column defined as vector(384)).

 Configuration via environment variables - see hindsight_api.config for all env var names.
 """
@@ -16,25 +16,12 @@ from abc import ABC, abstractmethod
 import httpx

 from ..config import (
-    DEFAULT_EMBEDDINGS_COHERE_MODEL,
-    DEFAULT_EMBEDDINGS_LITELLM_MODEL,
    DEFAULT_EMBEDDINGS_LOCAL_MODEL,
-    DEFAULT_EMBEDDINGS_OPENAI_MODEL,
    DEFAULT_EMBEDDINGS_PROVIDER,
-    DEFAULT_LITELLM_API_BASE,
-    ENV_COHERE_API_KEY,
-    ENV_EMBEDDINGS_COHERE_BASE_URL,
-    ENV_EMBEDDINGS_COHERE_MODEL,
-    ENV_EMBEDDINGS_LITELLM_MODEL,
+    EMBEDDING_DIMENSION,
    ENV_EMBEDDINGS_LOCAL_MODEL,
-    ENV_EMBEDDINGS_OPENAI_API_KEY,
-    ENV_EMBEDDINGS_OPENAI_BASE_URL,
-    ENV_EMBEDDINGS_OPENAI_MODEL,
    ENV_EMBEDDINGS_PROVIDER,
    ENV_EMBEDDINGS_TEI_URL,
-    ENV_LITELLM_API_BASE,
-    ENV_LITELLM_API_KEY,
-    ENV_LLM_API_KEY,
 )

 logger = logging.getLogger(__name__)
@@ -44,8 +31,8 @@ class Embeddings(ABC):
    """
    Abstract base class for embedding generation.

-    The embedding dimension is determined by the model and detected at initialization.
-    The database schema is automatically adjusted to match the model's dimension.
+    All implementations MUST generate 384-dimensional embeddings to match
+    the database schema.
    """

    @property
@@ -54,12 +41,6 @@ class Embeddings(ABC):
        """Return a human-readable name for this provider (e.g., 'local', 'tei')."""
        pass

-    @property
-    @abstractmethod
-    def dimension(self) -> int:
-        """Return the embedding dimension produced by this model."""
-        pass
-
    @abstractmethod
    async def initialize(self) -> None:
        """
@@ -73,13 +54,13 @@ class Embeddings(ABC):
    @abstractmethod
    def encode(self, texts: list[str]) -> list[list[float]]:
        """
-        Generate embeddings for a list of texts.
+        Generate 384-dimensional embeddings for a list of texts.

        Args:
            texts: List of text strings to encode

        Returns:
-            List of embedding vectors (each is a list of floats)
+            List of 384-dimensional embedding vectors (each is a list of floats)
        """
        pass

@@ -89,7 +70,9 @@ class LocalSTEmbeddings(Embeddings):
    Local embeddings implementation using SentenceTransformers.

    Call initialize() during startup to load the model and avoid cold starts.
-    The embedding dimension is auto-detected from the model.
+
+    Default model is BAAI/bge-small-en-v1.5 which produces 384-dimensional
+    embeddings matching the database schema.
    """

    def __init__(self, model_name: str | None = None):
@@ -98,22 +81,16 @@ class LocalSTEmbeddings(Embeddings):

        Args:
            model_name: Name of the SentenceTransformer model to use.
+                       Must produce 384-dimensional embeddings.
                       Default: BAAI/bge-small-en-v1.5
        """
        self.model_name = model_name or DEFAULT_EMBEDDINGS_LOCAL_MODEL
        self._model = None
-        self._dimension: int | None = None

    @property
    def provider_name(self) -> str:
        return "local"

-    @property
-    def dimension(self) -> int:
-        if self._dimension is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-        return self._dimension
-
    async def initialize(self) -> None:
        """Load the embedding model."""
        if self._model is not None:
@@ -135,18 +112,26 @@ class LocalSTEmbeddings(Embeddings):
            model_kwargs={"low_cpu_mem_usage": False, "device_map": None},
        )

-        self._dimension = self._model.get_sentence_embedding_dimension()
-        logger.info(f"Embeddings: local provider initialized (dim: {self._dimension})")
+        # Validate dimension matches database schema
+        model_dim = self._model.get_sentence_embedding_dimension()
+        if model_dim != EMBEDDING_DIMENSION:
+            raise ValueError(
+                f"Model {self.model_name} produces {model_dim}-dimensional embeddings, "
+                f"but database schema requires {EMBEDDING_DIMENSION} dimensions. "
+                f"Use a model that produces {EMBEDDING_DIMENSION}-dimensional embeddings."
+            )
+
+        logger.info(f"Embeddings: local provider initialized (dim: {model_dim})")

    def encode(self, texts: list[str]) -> list[list[float]]:
        """
-        Generate embeddings for a list of texts.
+        Generate 384-dimensional embeddings for a list of texts.

        Args:
            texts: List of text strings to encode

        Returns:
-            List of embedding vectors
+            List of 384-dimensional embedding vectors
        """
        if self._model is None:
            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
@@ -161,7 +146,7 @@ class RemoteTEIEmbeddings(Embeddings):
    TEI provides a high-performance inference server for embedding models.
    See: https://github.com/huggingface/text-embeddings-inference

-    The embedding dimension is auto-detected from the server at initialization.
+    The server should be running a model that produces 384-dimensional embeddings.
    """

    def __init__(
@@ -189,18 +174,11 @@ class RemoteTEIEmbeddings(Embeddings):
        self.retry_delay = retry_delay
        self._client: httpx.Client | None = None
        self._model_id: str | None = None
-        self._dimension: int | None = None

    @property
    def provider_name(self) -> str:
        return "tei"

-    @property
-    def dimension(self) -> int:
-        if self._dimension is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-        return self._dimension
-
    def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
        """Make an HTTP request with automatic retries on transient errors."""
        import time
@@ -251,24 +229,7 @@ class RemoteTEIEmbeddings(Embeddings):
            response = self._request_with_retry("GET", f"{self.base_url}/info")
            info = response.json()
            self._model_id = info.get("model_id", "unknown")
-
-            # Get dimension from server info or by doing a test embedding
-            if "max_input_length" in info and "model_dtype" in info:
-                # Try to get dimension from info endpoint (some TEI versions expose it)
-                # If not available, do a test embedding
-                pass
-
-            # Do a test embedding to detect dimension
-            test_response = self._request_with_retry(
-                "POST",
-                f"{self.base_url}/embed",
-                json={"inputs": ["test"]},
-            )
-            test_embeddings = test_response.json()
-            if test_embeddings and len(test_embeddings) > 0:
-                self._dimension = len(test_embeddings[0])
-
-            logger.info(f"Embeddings: TEI provider initialized (model: {self._model_id}, dim: {self._dimension})")
+            logger.info(f"Embeddings: TEI provider initialized (model: {self._model_id})")
        except httpx.HTTPError as e:
            raise RuntimeError(f"Failed to connect to TEI server at {self.base_url}: {e}")

@@ -308,369 +269,6 @@ class RemoteTEIEmbeddings(Embeddings):
        return all_embeddings


-class OpenAIEmbeddings(Embeddings):
-    """
-    OpenAI embeddings implementation using the OpenAI API.
-
-    Supports text-embedding-3-small (1536 dims), text-embedding-3-large (3072 dims),
-    and text-embedding-ada-002 (1536 dims, legacy).
-
-    The embedding dimension is auto-detected from the model at initialization.
-    """
-
-    # Known dimensions for OpenAI embedding models
-    MODEL_DIMENSIONS = {
-        "text-embedding-3-small": 1536,
-        "text-embedding-3-large": 3072,
-        "text-embedding-ada-002": 1536,
-    }
-
-    def __init__(
-        self,
-        api_key: str,
-        model: str = DEFAULT_EMBEDDINGS_OPENAI_MODEL,
-        base_url: str | None = None,
-        batch_size: int = 100,
-        max_retries: int = 3,
-    ):
-        """
-        Initialize OpenAI embeddings client.
-
-        Args:
-            api_key: OpenAI API key
-            model: OpenAI embedding model name (default: text-embedding-3-small)
-            base_url: Custom base URL for OpenAI-compatible API (e.g., Azure OpenAI endpoint)
-            batch_size: Maximum batch size for embedding requests (default: 100)
-            max_retries: Maximum number of retries for failed requests (default: 3)
-        """
-        self.api_key = api_key
-        self.model = model
-        self.base_url = base_url
-        self.batch_size = batch_size
-        self.max_retries = max_retries
-        self._client = None
-        self._dimension: int | None = None
-
-    @property
-    def provider_name(self) -> str:
-        return "openai"
-
-    @property
-    def dimension(self) -> int:
-        if self._dimension is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-        return self._dimension
-
-    async def initialize(self) -> None:
-        """Initialize the OpenAI client and detect dimension."""
-        if self._client is not None:
-            return
-
-        try:
-            from openai import OpenAI
-        except ImportError:
-            raise ImportError("openai is required for OpenAIEmbeddings. Install it with: pip install openai")
-
-        base_url_msg = f" at {self.base_url}" if self.base_url else ""
-        logger.info(f"Embeddings: initializing OpenAI provider with model {self.model}{base_url_msg}")
-
-        # Build client kwargs, only including base_url if set (for Azure or custom endpoints)
-        client_kwargs = {"api_key": self.api_key, "max_retries": self.max_retries}
-        if self.base_url:
-            client_kwargs["base_url"] = self.base_url
-        self._client = OpenAI(**client_kwargs)
-
-        # Try to get dimension from known models, otherwise do a test embedding
-        if self.model in self.MODEL_DIMENSIONS:
-            self._dimension = self.MODEL_DIMENSIONS[self.model]
-        else:
-            # Do a test embedding to detect dimension
-            response = self._client.embeddings.create(
-                model=self.model,
-                input=["test"],
-            )
-            if response.data:
-                self._dimension = len(response.data[0].embedding)
-
-        logger.info(f"Embeddings: OpenAI provider initialized (model: {self.model}, dim: {self._dimension})")
-
-    def encode(self, texts: list[str]) -> list[list[float]]:
-        """
-        Generate embeddings using the OpenAI API.
-
-        Args:
-            texts: List of text strings to encode
-
-        Returns:
-            List of embedding vectors
-        """
-        if self._client is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-
-        if not texts:
-            return []
-
-        all_embeddings = []
-
-        # Process in batches
-        for i in range(0, len(texts), self.batch_size):
-            batch = texts[i : i + self.batch_size]
-
-            response = self._client.embeddings.create(
-                model=self.model,
-                input=batch,
-            )
-
-            # Sort by index to ensure correct order
-            batch_embeddings = sorted(response.data, key=lambda x: x.index)
-            all_embeddings.extend([e.embedding for e in batch_embeddings])
-
-        return all_embeddings
-
-
-class CohereEmbeddings(Embeddings):
-    """
-    Cohere embeddings implementation using the Cohere API.
-
-    Supports embed-english-v3.0 (1024 dims) and embed-multilingual-v3.0 (1024 dims).
-
-    The embedding dimension is auto-detected from the model at initialization.
-    """
-
-    # Known dimensions for Cohere embedding models
-    MODEL_DIMENSIONS = {
-        "embed-english-v3.0": 1024,
-        "embed-multilingual-v3.0": 1024,
-        "embed-english-light-v3.0": 384,
-        "embed-multilingual-light-v3.0": 384,
-        "embed-english-v2.0": 4096,
-        "embed-multilingual-v2.0": 768,
-    }
-
-    def __init__(
-        self,
-        api_key: str,
-        model: str = DEFAULT_EMBEDDINGS_COHERE_MODEL,
-        base_url: str | None = None,
-        batch_size: int = 96,
-        timeout: float = 60.0,
-        input_type: str = "search_document",
-    ):
-        """
-        Initialize Cohere embeddings client.
-
-        Args:
-            api_key: Cohere API key
-            model: Cohere embedding model name (default: embed-english-v3.0)
-            base_url: Custom base URL for Cohere-compatible API (e.g., Azure-hosted endpoint)
-            batch_size: Maximum batch size for embedding requests (default: 96, Cohere's limit)
-            timeout: Request timeout in seconds (default: 60.0)
-            input_type: Input type for embeddings (default: search_document).
-                       Options: search_document, search_query, classification, clustering
-        """
-        self.api_key = api_key
-        self.model = model
-        self.base_url = base_url
-        self.batch_size = batch_size
-        self.timeout = timeout
-        self.input_type = input_type
-        self._client = None
-        self._dimension: int | None = None
-
-    @property
-    def provider_name(self) -> str:
-        return "cohere"
-
-    @property
-    def dimension(self) -> int:
-        if self._dimension is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-        return self._dimension
-
-    async def initialize(self) -> None:
-        """Initialize the Cohere client and detect dimension."""
-        if self._client is not None:
-            return
-
-        try:
-            import cohere
-        except ImportError:
-            raise ImportError("cohere is required for CohereEmbeddings. Install it with: pip install cohere")
-
-        base_url_msg = f" at {self.base_url}" if self.base_url else ""
-        logger.info(f"Embeddings: initializing Cohere provider with model {self.model}{base_url_msg}")
-
-        # Build client kwargs, only including base_url if set (for Azure or custom endpoints)
-        client_kwargs = {"api_key": self.api_key, "timeout": self.timeout}
-        if self.base_url:
-            client_kwargs["base_url"] = self.base_url
-        self._client = cohere.Client(**client_kwargs)
-
-        # Try to get dimension from known models, otherwise do a test embedding
-        if self.model in self.MODEL_DIMENSIONS:
-            self._dimension = self.MODEL_DIMENSIONS[self.model]
-        else:
-            # Do a test embedding to detect dimension
-            response = self._client.embed(
-                texts=["test"],
-                model=self.model,
-                input_type=self.input_type,
-            )
-            if response.embeddings:
-                self._dimension = len(response.embeddings[0])
-
-        logger.info(f"Embeddings: Cohere provider initialized (model: {self.model}, dim: {self._dimension})")
-
-    def encode(self, texts: list[str]) -> list[list[float]]:
-        """
-        Generate embeddings using the Cohere API.
-
-        Args:
-            texts: List of text strings to encode
-
-        Returns:
-            List of embedding vectors
-        """
-        if self._client is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-
-        if not texts:
-            return []
-
-        all_embeddings = []
-
-        # Process in batches
-        for i in range(0, len(texts), self.batch_size):
-            batch = texts[i : i + self.batch_size]
-
-            response = self._client.embed(
-                texts=batch,
-                model=self.model,
-                input_type=self.input_type,
-            )
-
-            all_embeddings.extend(response.embeddings)
-
-        return all_embeddings
-
-
-class LiteLLMEmbeddings(Embeddings):
-    """
-    LiteLLM embeddings implementation using LiteLLM proxy's /embeddings endpoint.
-
-    LiteLLM provides a unified interface for multiple embedding providers.
-    The proxy exposes an OpenAI-compatible /embeddings endpoint.
-    See: https://docs.litellm.ai/docs/embedding/supported_embedding
-
-    Supported providers via LiteLLM:
-    - OpenAI (text-embedding-3-small, text-embedding-ada-002, etc.)
-    - Cohere (embed-english-v3.0, etc.) - prefix with cohere/
-    - Vertex AI (textembedding-gecko, etc.) - prefix with vertex_ai/
-    - HuggingFace, Mistral, Voyage AI, etc.
-
-    The embedding dimension is auto-detected from the model at initialization.
-    """
-
-    def __init__(
-        self,
-        api_base: str = DEFAULT_LITELLM_API_BASE,
-        api_key: str | None = None,
-        model: str = DEFAULT_EMBEDDINGS_LITELLM_MODEL,
-        batch_size: int = 100,
-        timeout: float = 60.0,
-    ):
-        """
-        Initialize LiteLLM embeddings client.
-
-        Args:
-            api_base: Base URL of the LiteLLM proxy (default: http://localhost:4000)
-            api_key: API key for the LiteLLM proxy (optional, depends on proxy config)
-            model: Embedding model name (default: text-embedding-3-small)
-                   Use provider prefix for non-OpenAI models (e.g., cohere/embed-english-v3.0)
-            batch_size: Maximum batch size for embedding requests (default: 100)
-            timeout: Request timeout in seconds (default: 60.0)
-        """
-        self.api_base = api_base.rstrip("/")
-        self.api_key = api_key
-        self.model = model
-        self.batch_size = batch_size
-        self.timeout = timeout
-        self._client: httpx.Client | None = None
-        self._dimension: int | None = None
-
-    @property
-    def provider_name(self) -> str:
-        return "litellm"
-
-    @property
-    def dimension(self) -> int:
-        if self._dimension is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-        return self._dimension
-
-    async def initialize(self) -> None:
-        """Initialize the HTTP client and detect embedding dimension."""
-        if self._client is not None:
-            return
-
-        logger.info(f"Embeddings: initializing LiteLLM provider at {self.api_base} with model {self.model}")
-
-        headers = {"Content-Type": "application/json"}
-        if self.api_key:
-            headers["Authorization"] = f"Bearer {self.api_key}"
-
-        self._client = httpx.Client(timeout=self.timeout, headers=headers)
-
-        # Do a test embedding to detect dimension
-        try:
-            response = self._client.post(
-                f"{self.api_base}/embeddings",
-                json={"model": self.model, "input": ["test"]},
-            )
-            response.raise_for_status()
-            result = response.json()
-            if result.get("data") and len(result["data"]) > 0:
-                self._dimension = len(result["data"][0]["embedding"])
-            logger.info(f"Embeddings: LiteLLM provider initialized (model: {self.model}, dim: {self._dimension})")
-        except httpx.HTTPError as e:
-            raise RuntimeError(f"Failed to connect to LiteLLM proxy at {self.api_base}: {e}")
-
-    def encode(self, texts: list[str]) -> list[list[float]]:
-        """
-        Generate embeddings using the LiteLLM proxy.
-
-        Args:
-            texts: List of text strings to encode
-
-        Returns:
-            List of embedding vectors
-        """
-        if self._client is None:
-            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-
-        if not texts:
-            return []
-
-        all_embeddings = []
-
-        # Process in batches
-        for i in range(0, len(texts), self.batch_size):
-            batch = texts[i : i + self.batch_size]
-
-            response = self._client.post(
-                f"{self.api_base}/embeddings",
-                json={"model": self.model, "input": batch},
-            )
-            response.raise_for_status()
-            result = response.json()
-
-            # Sort by index to ensure correct order
-            batch_embeddings = sorted(result["data"], key=lambda x: x["index"])
-            all_embeddings.extend([e["embedding"] for e in batch_embeddings])
-
-        return all_embeddings
-
-
 def create_embeddings_from_env() -> Embeddings:
    """
    Create an Embeddings instance based on environment variables.
@@ -691,30 +289,5 @@ def create_embeddings_from_env() -> Embeddings:
        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)
-        if not api_key:
-            raise ValueError(
-                f"{ENV_EMBEDDINGS_OPENAI_API_KEY} or {ENV_LLM_API_KEY} is required "
-                f"when {ENV_EMBEDDINGS_PROVIDER} is 'openai'"
-            )
-        model = os.environ.get(ENV_EMBEDDINGS_OPENAI_MODEL, DEFAULT_EMBEDDINGS_OPENAI_MODEL)
-        base_url = os.environ.get(ENV_EMBEDDINGS_OPENAI_BASE_URL) or None
-        return OpenAIEmbeddings(api_key=api_key, model=model, base_url=base_url)
-    elif provider == "cohere":
-        api_key = os.environ.get(ENV_COHERE_API_KEY)
-        if not api_key:
-            raise ValueError(f"{ENV_COHERE_API_KEY} is required when {ENV_EMBEDDINGS_PROVIDER} is 'cohere'")
-        model = os.environ.get(ENV_EMBEDDINGS_COHERE_MODEL, DEFAULT_EMBEDDINGS_COHERE_MODEL)
-        base_url = os.environ.get(ENV_EMBEDDINGS_COHERE_BASE_URL) or None
-        return CohereEmbeddings(api_key=api_key, model=model, base_url=base_url)
-    elif provider == "litellm":
-        api_base = os.environ.get(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE)
-        api_key = os.environ.get(ENV_LITELLM_API_KEY)
-        model = os.environ.get(ENV_EMBEDDINGS_LITELLM_MODEL, DEFAULT_EMBEDDINGS_LITELLM_MODEL)
-        return LiteLLMEmbeddings(api_base=api_base, api_key=api_key, model=model)
    else:
-        raise ValueError(
-            f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei', 'openai', 'cohere', 'litellm'"
-        )
+        raise ValueError(f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei'")
@@ -209,7 +209,7 @@ class EntityResolver:
        # This handles duplicates via ON CONFLICT and returns all IDs
        if entities_to_create:
            # Group entities by canonical name (lowercase) to handle duplicates within batch
-            # For duplicates, we only insert once and reuse the ID, but track the count
+            # For duplicates, we only insert once and reuse the ID
            unique_entities = {}  # lowercase_name -> (entity_data, event_date, [indices])
            for idx, entity_data, event_date in entities_to_create:
                name_lower = entity_data["text"].lower()
@@ -223,32 +223,29 @@ class EntityResolver:
            # Use a single query with unnest for speed
            entity_names = []
            entity_dates = []
-            entity_counts = []  # Track how many times each entity appears in this batch
            indices_map = []  # Maps result index -> list of original indices

            for name_lower, (entity_data, event_date, indices) in unique_entities.items():
                entity_names.append(entity_data["text"])
                entity_dates.append(event_date)
-                entity_counts.append(len(indices))  # Count of occurrences in this batch
                indices_map.append(indices)

            # Batch INSERT ... ON CONFLICT with RETURNING
-            # Uses the batch count for mention_count instead of always 1
+            # This is much faster than individual inserts
            rows = await conn.fetch(
                f"""
                INSERT INTO {fq_table("entities")} (bank_id, canonical_name, first_seen, last_seen, mention_count)
-                SELECT $1, name, event_date, event_date, cnt
-                FROM unnest($2::text[], $3::timestamptz[], $4::int[]) AS t(name, event_date, cnt)
+                SELECT $1, name, event_date, event_date, 1
+                FROM unnest($2::text[], $3::timestamptz[]) AS t(name, event_date)
                ON CONFLICT (bank_id, LOWER(canonical_name))
                DO UPDATE SET
-                    mention_count = {fq_table("entities")}.mention_count + EXCLUDED.mention_count,
+                    mention_count = {fq_table("entities")}.mention_count + 1,
                    last_seen = EXCLUDED.last_seen
                RETURNING id
                """,
                bank_id,
                entity_names,
                entity_dates,
-                entity_counts,
            )

            # Map returned IDs back to original indices
@@ -160,14 +160,14 @@ class MemoryEngineInterface(ABC):
        request_context: "RequestContext",
    ) -> dict[str, Any]:
        """
-        Get bank profile including disposition and mission.
+        Get bank profile including disposition and background.

        Args:
            bank_id: The memory bank ID.
            request_context: Request context for authentication.

        Returns:
-            Bank profile dict with bank_id, name, disposition, and mission.
+            Bank profile dict.
        """
        ...

@@ -190,44 +190,25 @@ class MemoryEngineInterface(ABC):
        ...

    @abstractmethod
-    async def merge_bank_mission(
+    async def merge_bank_background(
        self,
        bank_id: str,
        new_info: str,
        *,
+        update_disposition: bool = True,
        request_context: "RequestContext",
    ) -> dict[str, Any]:
        """
-        Merge new mission information into bank profile.
+        Merge new background information into bank profile.

        Args:
            bank_id: The memory bank ID.
-            new_info: New mission information to merge.
+            new_info: New background information to merge.
+            update_disposition: Whether to infer disposition from background.
            request_context: Request context for authentication.

        Returns:
-            Updated mission info.
-        """
-        ...
-
-    @abstractmethod
-    async def set_bank_mission(
-        self,
-        bank_id: str,
-        mission: str,
-        *,
-        request_context: "RequestContext",
-    ) -> dict[str, Any]:
-        """
-        Set the bank's mission (replaces existing).
-
-        Args:
-            bank_id: The memory bank ID.
-            mission: The mission text.
-            request_context: Request context for authentication.
-
-        Returns:
-            Dict with bank_id and mission.
+            Updated background info.
        """
        ...

@@ -308,7 +289,6 @@ class MemoryEngineInterface(ABC):
        bank_id: str,
        *,
        fact_type: str | None = None,
-        limit: int = 1000,
        request_context: "RequestContext",
    ) -> dict[str, Any]:
        """
@@ -317,11 +297,10 @@ class MemoryEngineInterface(ABC):
        Args:
            bank_id: The memory bank ID.
            fact_type: Filter by fact type.
-            limit: Maximum number of items to return (default: 1000).
            request_context: Request context for authentication.

        Returns:
-            Dict with nodes, edges, table_rows, total_units, limit.
+            Dict with nodes, edges, table_rows, total_units.
        """
        ...

@@ -425,20 +404,18 @@ class MemoryEngineInterface(ABC):
        bank_id: str,
        *,
        limit: int = 100,
-        offset: int = 0,
        request_context: "RequestContext",
-    ) -> dict[str, Any]:
+    ) -> list[dict[str, Any]]:
        """
-        List entities for a bank with pagination.
+        List entities for a bank.

        Args:
            bank_id: The memory bank ID.
            limit: Maximum results.
-            offset: Offset for pagination.
            request_context: Request context for authentication.

        Returns:
-            Dict with items, total, limit, offset.
+            List of entity dicts.
        """
        ...

@@ -537,7 +514,7 @@ class MemoryEngineInterface(ABC):
        bank_id: str,
        *,
        request_context: "RequestContext",
-    ) -> dict[str, Any]:
+    ) -> list[dict[str, Any]]:
        """
        List async operations for a bank.

@@ -546,7 +523,7 @@ class MemoryEngineInterface(ABC):
            request_context: Request context for authentication.

        Returns:
-            Dict with 'total' (int) and 'operations' (list of operation dicts).
+            List of operation dicts with id, task_type, status, etc.
        """
        ...

@@ -580,16 +557,16 @@ class MemoryEngineInterface(ABC):
        bank_id: str,
        *,
        name: str | None = None,
-        mission: str | None = None,
+        background: str | None = None,
        request_context: "RequestContext",
    ) -> dict[str, Any]:
        """
-        Update bank name and/or mission.
+        Update bank name and/or background.

        Args:
            bank_id: The memory bank ID.
            name: New bank name (optional).
-            mission: New mission text (optional, replaces existing).
+            background: New background text (optional, replaces existing).
            request_context: Request context for authentication.

        Returns:
@@ -19,12 +19,9 @@ from openai import APIConnectionError, APIStatusError, AsyncOpenAI, LengthFinish
 from ..config import (
    DEFAULT_LLM_MAX_CONCURRENT,
    DEFAULT_LLM_TIMEOUT,
-    ENV_LLM_GROQ_SERVICE_TIER,
    ENV_LLM_MAX_CONCURRENT,
    ENV_LLM_TIMEOUT,
 )
-from ..metrics import get_metrics_collector
-from .response_models import TokenUsage

 # Seed applied to every Groq request for deterministic behavior.
 DEFAULT_LLM_SEED = 4242
@@ -66,7 +63,6 @@ class LLMProvider:
        base_url: str,
        model: str,
        reasoning_effort: str = "low",
-        groq_service_tier: str | None = None,
    ):
        """
        Initialize LLM provider.
@@ -77,25 +73,18 @@ class LLMProvider:
            base_url: Base URL for the API.
            model: Model name.
            reasoning_effort: Reasoning effort level for supported providers.
-            groq_service_tier: Groq service tier ("on_demand", "flex", "auto"). Default: None (uses Groq's default).
        """
        self.provider = provider.lower()
        self.api_key = api_key
        self.base_url = base_url
        self.model = model
        self.reasoning_effort = reasoning_effort
-        # Default to 'auto' for best performance, users can override to 'on_demand' for free tier
-        self.groq_service_tier = groq_service_tier or os.getenv(ENV_LLM_GROQ_SERVICE_TIER, "auto")

        # Validate provider
-        valid_providers = ["openai", "groq", "ollama", "gemini", "anthropic", "lmstudio", "mock"]
+        valid_providers = ["openai", "groq", "ollama", "gemini", "anthropic", "lmstudio"]
        if self.provider not in valid_providers:
            raise ValueError(f"Invalid LLM provider: {self.provider}. Must be one of: {', '.join(valid_providers)}")

-        # Mock provider tracking (for testing)
-        self._mock_calls: list[dict] = []
-        self._mock_response: Any = None
-
        # Set default base URLs
        if not self.base_url:
            if self.provider == "groq":
@@ -105,8 +94,8 @@ class LLMProvider:
            elif self.provider == "lmstudio":
                self.base_url = "http://localhost:1234/v1"

-        # Validate API key (not needed for ollama, lmstudio, or mock)
-        if self.provider not in ("ollama", "lmstudio", "mock") and not self.api_key:
+        # Validate API key (not needed for ollama or lmstudio)
+        if self.provider not in ("ollama", "lmstudio") and not self.api_key:
            raise ValueError(f"API key not found for {self.provider}")

        # Get timeout config (set HINDSIGHT_API_LLM_TIMEOUT for local LLMs that need longer timeouts)
@@ -117,10 +106,7 @@ class LLMProvider:
        self._gemini_client = None
        self._anthropic_client = None

-        if self.provider == "mock":
-            # Mock provider - no client needed
-            pass
-        elif self.provider == "gemini":
+        if self.provider == "gemini":
            self._gemini_client = genai.Client(api_key=self.api_key)
        elif self.provider == "anthropic":
            from anthropic import AsyncAnthropic
@@ -183,7 +169,6 @@ class LLMProvider:
        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.
@@ -199,43 +184,21 @@ class LLMProvider:
            max_backoff: Maximum backoff time in seconds.
            skip_validation: Return raw JSON without Pydantic validation.
            strict_schema: Use strict JSON schema enforcement (OpenAI only). Guarantees all required fields.
-            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 from the LLM call.
+            Parsed response if response_format is provided, otherwise text content.

        Raises:
            OutputTooLongError: If output exceeds token limits.
            Exception: Re-raises API errors after retries exhausted.
        """
-        semaphore_start = time.time()
        async with _global_llm_semaphore:
-            semaphore_wait_time = time.time() - semaphore_start
            start_time = time.time()

-            # Handle Mock provider (for testing)
-            if self.provider == "mock":
-                return await self._call_mock(
-                    messages,
-                    response_format,
-                    scope,
-                    return_usage,
-                )
-
            # Handle Gemini provider separately
            if self.provider == "gemini":
                return await self._call_gemini(
-                    messages,
-                    response_format,
-                    max_retries,
-                    initial_backoff,
-                    max_backoff,
-                    skip_validation,
-                    start_time,
-                    scope,
-                    return_usage,
-                    semaphore_wait_time,
+                    messages, response_format, max_retries, initial_backoff, max_backoff, skip_validation, start_time
                )

            # Handle Anthropic provider separately
@@ -249,9 +212,6 @@ class LLMProvider:
                    max_backoff,
                    skip_validation,
                    start_time,
-                    scope,
-                    return_usage,
-                    semaphore_wait_time,
                )

            # Handle Ollama with native API for structured output (better schema enforcement)
@@ -266,9 +226,6 @@ class LLMProvider:
                    max_backoff,
                    skip_validation,
                    start_time,
-                    scope,
-                    return_usage,
-                    semaphore_wait_time,
                )

            call_params = {
@@ -306,56 +263,51 @@ class LLMProvider:
            # Provider-specific parameters
            if self.provider == "groq":
                call_params["seed"] = DEFAULT_LLM_SEED
-                extra_body: dict[str, Any] = {}
-                # Add service_tier if configured (requires paid plan for flex/auto)
-                if self.groq_service_tier:
-                    extra_body["service_tier"] = self.groq_service_tier
-                # Add reasoning parameters for reasoning models
+                extra_body = {"service_tier": "auto"}
+                # Only add reasoning parameters for reasoning models
                if is_reasoning_model:
                    extra_body["include_reasoning"] = False
-                if extra_body:
-                    call_params["extra_body"] = extra_body
+                call_params["extra_body"] = extra_body

            last_exception = None

-            # Prepare response format ONCE before the retry loop
-            # (to avoid appending schema to messages on every retry)
-            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
-                    # This guarantees all required fields are returned
-                    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":
-                            call_params["messages"][0]["content"] += schema_msg
-                        elif call_params["messages"]:
-                            call_params["messages"][0]["content"] = (
-                                schema_msg + "\n\n" + call_params["messages"][0]["content"]
-                            )
-                    if self.provider not in ("lmstudio", "ollama"):
-                        # LM Studio and Ollama don't support json_object response format reliably
-                        # We rely on the schema in the system message instead
-                        call_params["response_format"] = {"type": "json_object"}
-
            for attempt in range(max_retries + 1):
                try:
                    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
+                            # This guarantees all required fields are returned
+                            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":
+                                    call_params["messages"][0]["content"] += schema_msg
+                                elif call_params["messages"]:
+                                    call_params["messages"][0]["content"] = (
+                                        schema_msg + "\n\n" + call_params["messages"][0]["content"]
+                                    )
+                            if self.provider not in ("lmstudio", "ollama"):
+                                # LM Studio and Ollama don't support json_object response format reliably
+                                # We rely on the schema in the system message instead
+                                call_params["response_format"] = {"type": "json_object"}
+
+                        logger.debug(f"Sending request to {self.provider}/{self.model} (timeout={self.timeout})")
                        response = await self._client.chat.completions.create(**call_params)
+                        logger.debug(f"Received response from {self.provider}/{self.model}")

                        content = response.choices[0].message.content

@@ -418,46 +370,21 @@ class LLMProvider:
                        response = await self._client.chat.completions.create(**call_params)
                        result = response.choices[0].message.content

-                    # Record token usage metrics
+                    # Log slow calls
                    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,
-                    )
-
-                    # Log slow calls
-                    if duration > 10.0 and usage:
-                        ratio = max(1, output_tokens) / max(1, input_tokens)
+                    if duration > 10.0:
+                        ratio = max(1, usage.completion_tokens) / usage.prompt_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 ""
-                        wait_info = f", wait={semaphore_wait_time:.3f}s" if semaphore_wait_time > 0.1 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{wait_info}, ratio out/in={ratio:.2f}"
+                            f"slow llm call: model={self.provider}/{self.model}, "
+                            f"input_tokens={usage.prompt_tokens}, output_tokens={usage.completion_tokens}, "
+                            f"total_tokens={usage.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:
@@ -468,11 +395,13 @@ class LLMProvider:

                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:
+                        status_code = getattr(e, "status_code", None) or getattr(
+                            getattr(e, "response", None), "status_code", None
+                        )
+                        logger.warning(
+                            f"Connection error, retrying... (attempt {attempt + 1}/{max_retries + 1}) - status_code={status_code}, message={e}"
+                        )
                        backoff = min(initial_backoff * (2**attempt), max_backoff)
                        await asyncio.sleep(backoff)
                        continue
@@ -486,45 +415,6 @@ class LLMProvider:
                        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
-                    # Convert to expected JSON format and continue
-                    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 the tool call format and convert to actions format
-                                        tool_call = json.loads(failed_gen)
-                                        tool_name = tool_call.get("name", "")
-                                        tool_args = tool_call.get("arguments", {})
-                                        # Convert to actions format: {"actions": [{"tool": "name", ...args}]}
-                                        converted = {"actions": [{"tool": tool_name, **tool_args}]}
-                                        if skip_validation:
-                                            result = converted
-                                        else:
-                                            result = response_format.model_validate(converted)
-
-                                        # Record metrics for this successful recovery
-                                        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)
@@ -535,416 +425,14 @@ class LLMProvider:
                        logger.error(f"API error after {max_retries + 1} attempts: {str(e)}")
                        raise

-                except Exception:
+                except Exception as e:
+                    logger.error(f"Unexpected error during LLM call: {type(e).__name__}: {str(e)}")
                    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 {"type": "function", "function": {"name": "..."}}
-
-        Returns:
-            LLMToolCallResult with content and/or tool_calls.
-        """
-        from .response_models import LLMToolCall, LLMToolCallResult
-
-        async with _global_llm_semaphore:
-            start_time = time.time()
-
-            # Handle Mock provider
-            if self.provider == "mock":
-                return await self._call_with_tools_mock(messages, tools, scope)
-
-            # Handle Anthropic separately (uses different tool format)
-            if self.provider == "anthropic":
-                return await self._call_with_tools_anthropic(
-                    messages, tools, max_completion_tokens, max_retries, initial_backoff, max_backoff, start_time, scope
-                )
-
-            # Handle Gemini (convert to Gemini tool format)
-            if self.provider == "gemini":
-                return await self._call_with_tools_gemini(
-                    messages, tools, max_retries, initial_backoff, max_backoff, start_time, scope
-                )
-
-            # OpenAI-compatible providers (OpenAI, Groq, Ollama, LMStudio)
-            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,
-                    )
-
-                    return LLMToolCallResult(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
-
-                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_with_tools_mock(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        scope: str,
-    ) -> "LLMToolCallResult":
-        """Handle mock tool calls for testing."""
-        from .response_models import LLMToolCallResult
-
-        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)
-
-        if self._mock_response is not None:
-            if isinstance(self._mock_response, LLMToolCallResult):
-                return self._mock_response
-            # Allow setting just tool calls as a list
-            if isinstance(self._mock_response, list):
-                from .response_models import LLMToolCall
-
-                return 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",
-                )
-
-        return LLMToolCallResult(content="mock response", finish_reason="stop")
-
-    async def _call_with_tools_anthropic(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_completion_tokens: int | None,
-        max_retries: int,
-        initial_backoff: float,
-        max_backoff: float,
-        start_time: float,
-        scope: str,
-    ) -> "LLMToolCallResult":
-        """Handle Anthropic tool calling."""
-        from anthropic import APIConnectionError, APIStatusError
-
-        from .response_models import LLMToolCall, LLMToolCallResult
-
-        # 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
-
-        last_exception = None
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._anthropic_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"
-
-                # Record metrics
-                metrics = get_metrics_collector()
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=time.time() - start_time,
-                    input_tokens=response.usage.input_tokens or 0,
-                    output_tokens=response.usage.output_tokens or 0,
-                    success=True,
-                )
-
-                return LLMToolCallResult(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
-
-            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 _call_with_tools_gemini(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        max_retries: int,
-        initial_backoff: float,
-        max_backoff: float,
-        start_time: float,
-        scope: str,
-    ) -> "LLMToolCallResult":
-        """Handle Gemini tool calling."""
-        from .response_models import LLMToolCall, LLMToolCallResult
-
-        # 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 = genai_types.GenerateContentConfig(
-            system_instruction=system_instruction,
-            tools=gemini_tools,
-        )
-
-        last_exception = None
-        for attempt in range(max_retries + 1):
-            try:
-                response = await self._gemini_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:
-                    for part in response.candidates[0].content.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"
-
-                # Record metrics
-                metrics = get_metrics_collector()
-                input_tokens = response.usage_metadata.prompt_token_count if response.usage_metadata else 0
-                output_tokens = response.usage_metadata.candidates_token_count if response.usage_metadata else 0
-                metrics.record_llm_call(
-                    provider=self.provider,
-                    model=self.model,
-                    scope=scope,
-                    duration=time.time() - start_time,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-
-                return LLMToolCallResult(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
-
-            except genai_errors.APIError as e:
-                if e.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("Gemini tool call failed")
-
    async def _call_anthropic(
        self,
        messages: list[dict[str, str]],
@@ -955,9 +443,6 @@ class LLMProvider:
        max_backoff: float,
        skip_validation: bool,
        start_time: float,
-        scope: str = "memory",
-        return_usage: bool = False,
-        semaphore_wait_time: float = 0.0,
    ) -> Any:
        """Handle Anthropic-specific API calls."""
        from anthropic import APIConnectionError, APIStatusError, RateLimitError
@@ -1030,40 +515,17 @@ class LLMProvider:
                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,
-                )
-
                # Log slow calls
+                duration = time.time() - start_time
                if duration > 10.0:
-                    wait_info = f", wait={semaphore_wait_time:.3f}s" if semaphore_wait_time > 0.1 else ""
+                    input_tokens = response.usage.input_tokens
+                    output_tokens = response.usage.output_tokens
                    logger.info(
-                        f"slow llm call: scope={scope}, model={self.provider}/{self.model}, "
+                        f"slow llm call: model={self.provider}/{self.model}, "
                        f"input_tokens={input_tokens}, output_tokens={output_tokens}, "
-                        f"time={duration:.3f}s{wait_info}"
+                        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:
@@ -1118,9 +580,6 @@ class LLMProvider:
        max_backoff: float,
        skip_validation: bool,
        start_time: float,
-        scope: str = "memory",
-        return_usage: bool = False,
-        semaphore_wait_time: float = 0.0,
    ) -> Any:
        """
        Call Ollama using native API with JSON schema enforcement.
@@ -1195,39 +654,11 @@ class LLMProvider:
                        else:
                            raise

-                    # Extract token usage from Ollama response
-                    # Ollama returns prompt_eval_count (input) and eval_count (output)
-                    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
+                        return 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
+                        return response_format.model_validate(json_data)

                except httpx.HTTPStatusError as e:
                    last_exception = e
@@ -1270,9 +701,6 @@ class LLMProvider:
        max_backoff: float,
        skip_validation: bool,
        start_time: float,
-        scope: str = "memory",
-        return_usage: bool = False,
-        semaphore_wait_time: float = 0.0,
    ) -> Any:
        """Handle Gemini-specific API calls."""
        # Convert OpenAI-style messages to Gemini format
@@ -1349,43 +777,16 @@ class LLMProvider:
                else:
                    result = content

-                # Record metrics and log slow calls
-                duration = time.time() - start_time
-                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 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,
-                )
-
                # Log slow calls
-                if duration > 10.0 and input_tokens > 0:
-                    wait_info = f", wait={semaphore_wait_time:.3f}s" if semaphore_wait_time > 0.1 else ""
+                duration = time.time() - start_time
+                if duration > 10.0 and hasattr(response, "usage_metadata") and response.usage_metadata:
+                    usage = response.usage_metadata
                    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{wait_info}"
+                        f"slow llm call: model={self.provider}/{self.model}, "
+                        f"input_tokens={usage.prompt_token_count}, output_tokens={usage.candidates_token_count}, "
+                        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:
@@ -1427,61 +828,6 @@ class LLMProvider:
            raise last_exception
        raise RuntimeError("Gemini call failed after all retries")

-    async def _call_mock(
-        self,
-        messages: list[dict[str, str]],
-        response_format: Any | None,
-        scope: str,
-        return_usage: bool,
-    ) -> Any:
-        """
-        Handle mock provider calls for testing.
-
-        Records the call and returns a configurable mock response.
-        """
-        # 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}")
-
-        # 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
-
-    def set_mock_response(self, response: Any) -> None:
-        """Set the response to return from mock calls."""
-        self._mock_response = response
-
-    def get_mock_calls(self) -> list[dict]:
-        """Get the list of recorded mock calls."""
-        return self._mock_calls
-
-    def clear_mock_calls(self) -> None:
-        """Clear the recorded mock calls."""
-        self._mock_calls = []
-
    @classmethod
    def for_memory(cls) -> "LLMProvider":
        """Create provider for memory operations from environment variables."""
@@ -1,18 +0,0 @@
-"""
-Mental models module for Hindsight.
-
-Mental models are synthesized summaries that represent understanding. They come
-in different subtypes based on how they were created:
-
- Structural: Derived from the bank's mission (e.g., "Be a PM for engineering team")
-  These are created upfront based on what any agent with this role would need.
-
- Emergent: Discovered from data patterns (named entities, temporal clusters, etc.)
-  These surface organically as facts are retained.
-
- Pinned: User-defined models that persist across refreshes.
-"""
-
-from .models import MentalModel, MentalModelSubtype
-
-__all__ = ["MentalModel", "MentalModelSubtype"]
@@ -1,311 +0,0 @@
-"""
-Emergent mental model detection and promotion.
-
-Emergent models are discovered from data patterns:
- Named entity extraction (people, projects, systems)
- Temporal clustering (events with multiple references)
- Causal patterns ("Because X, we do Y")
- Behavioral anchors ("After X, we started Y")
- Reference frequency (anything mentioned repeatedly)
-
-When a pattern is detected, it goes through a mission filter to check relevance,
-and if relevant, is promoted to a mental model.
-"""
-
-import logging
-from typing import TYPE_CHECKING
-
-from pydantic import BaseModel, Field
-
-from .models import EmergentCandidate
-
-if TYPE_CHECKING:
-    from ..llm_wrapper import LLMConfig
-
-logger = logging.getLogger(__name__)
-
-
-class MissionFilterCandidate(BaseModel):
-    """Result of mission filtering for a single candidate."""
-
-    name: str
-    promote: bool = Field(description="True if this is a specific named entity worth tracking")
-    reason: str = Field(description="Brief explanation for the decision")
-
-
-class MissionFilterResponse(BaseModel):
-    """Response from LLM for mission filtering."""
-
-    candidates: list[MissionFilterCandidate] = Field(description="Filtering decision for each candidate")
-
-
-def build_mission_filter_prompt(mission: str, candidates: list[EmergentCandidate]) -> str:
-    """Build the prompt for filtering candidates by mission relevance."""
-    candidate_list = "\n".join(
-        [f"- {c.name} (mentions: {c.mention_count}, method: {c.detection_method})" for c in candidates]
-    )
-
-    return f"""Filter these detected entities. For each one, decide: promote=true or promote=false.
-
-MISSION: {mission}
-
-DETECTED ENTITIES:
-{candidate_list}
-
-=== DECISION RULES ===
-
-Set promote=true ONLY for specific, named entities:
- Person names: "John", "Maria", "Alice Chen", "Dr. Smith"
- Named organizations: "Google", "Acme Corp", "Frontend Team"
- Named places: "Central Park Zoo", "NYC Office", "Building A"
- Named projects: "Project Phoenix", "Auth Service v2"
-
-Set promote=false for EVERYTHING ELSE, including:
- Common English words: user, support, help, family, kids, parents, friends, people, team, photo, nature, park, office, home, work, school, joy, love, hope, fear, anger, gratitude, kindness, passion, motivation, inspiration, encouragement, positivity, energy, community, connection, commitment, collaboration, growth, impact, difference, success, progress, change, education, volunteering, veterans, homeless, shelter, meeting, project, system, process, event
- Generic categories (even capitalized): Users, Customers, Team, Family, Kids, Veterans, Community
- Abstract concepts: motivation, inspiration, gratitude, commitment, resilience
-
-THE TEST: Is this a specific name you'd find in a contact list or org chart?
- "John" → YES (promote=true)
- "kids" → NO (promote=false)
- "community" → NO (promote=false)
- "Maria" → YES (promote=true)
- "park" → NO (promote=false)
-
-When in doubt, set promote=false."""
-
-
-def get_mission_filter_system_message() -> str:
-    """System message for mission filtering."""
-    return """You filter entities for promotion. Output JSON with 'candidates' array.
-
-Rules:
- promote=true ONLY for specific names (people, organizations, named places/projects)
- promote=false for common words, generic categories, abstract concepts
-
-Examples:
- "John" → promote=true (person name)
- "kids" → promote=false (generic category)
- "community" → promote=false (abstract concept)
- "Google" → promote=true (organization name)
- "motivation" → promote=false (abstract concept)
-
-When in doubt, promote=false. Most entities should be rejected."""
-
-
-async def filter_candidates_by_mission(
-    llm_config: "LLMConfig",
-    mission: str,
-    candidates: list[EmergentCandidate],
-) -> list[EmergentCandidate]:
-    """
-    Filter emergent candidates to keep only specific, named entities.
-
-    Args:
-        llm_config: LLM configuration
-        mission: The bank's mission (used for context)
-        candidates: List of detected candidates
-
-    Returns:
-        Filtered list of candidates that are specific named entities
-    """
-    if not candidates:
-        return []
-
-    if not mission:
-        # No mission = no filtering, keep all candidates
-        logger.debug("[EMERGENT] No mission set, skipping filter")
-        return candidates
-
-    prompt = build_mission_filter_prompt(mission, candidates)
-
-    try:
-        result = await llm_config.call(
-            messages=[
-                {"role": "system", "content": get_mission_filter_system_message()},
-                {"role": "user", "content": prompt},
-            ],
-            response_format=MissionFilterResponse,
-            scope="mental_model_mission_filter",
-        )
-
-        # Build name -> promote map
-        promote_map = {c.name: c.promote for c in result.candidates}
-
-        # Filter candidates
-        filtered = []
-        for candidate in candidates:
-            if candidate.name in promote_map:
-                if promote_map[candidate.name]:
-                    filtered.append(candidate)
-                    logger.debug(f"[EMERGENT] Promoting '{candidate.name}'")
-                else:
-                    logger.debug(f"[EMERGENT] Rejecting '{candidate.name}'")
-            else:
-                # Candidate not in response - reject by default
-                logger.debug(f"[EMERGENT] '{candidate.name}' not in response, rejecting")
-
-        logger.info(f"[EMERGENT] Mission filter: {len(filtered)}/{len(candidates)} candidates promoted")
-        return filtered
-
-    except Exception as e:
-        logger.warning(f"[EMERGENT] Mission filter failed, rejecting all candidates: {e}")
-        return []
-
-
-async def evaluate_emergent_models(
-    llm_config: "LLMConfig",
-    models: list[dict],
-) -> list[str]:
-    """
-    Evaluate existing emergent models to check if they should be kept.
-
-    This re-evaluates emergent models using the same filtering criteria
-    as new candidates. Models that are generic/abstract will be removed.
-
-    Args:
-        llm_config: LLM configuration
-        models: List of existing emergent model dicts with 'name', 'id'
-
-    Returns:
-        List of model IDs that should be REMOVED (no longer valid)
-    """
-    if not models:
-        return []
-
-    # Convert existing models to candidates for evaluation
-    candidates = [
-        EmergentCandidate(
-            name=m["name"],
-            detection_method="existing_emergent_model",
-            mention_count=0,
-        )
-        for m in models
-    ]
-
-    # Build a simple prompt for re-evaluation
-    names_list = "\n".join([f"- {m['name']}" for m in models])
-    prompt = f"""Re-evaluate these existing mental models. For each one, decide: promote=true (keep) or promote=false (remove).
-
-EXISTING MODELS:
-{names_list}
-
-=== DECISION RULES ===
-
-Set promote=true ONLY for specific, named entities:
- Person names: "John", "Maria", "Alice Chen", "Dr. Smith"
- Named organizations: "Google", "Acme Corp", "Frontend Team"
- Named places: "Central Park Zoo", "NYC Office", "Building A"
- Named projects: "Project Phoenix", "Auth Service v2"
-
-Set promote=false for EVERYTHING ELSE, including:
- Common English words: user, support, help, family, kids, parents, friends, people, team, photo, nature, park, office, home, work, school, joy, love, hope, fear, anger, gratitude, kindness, passion, motivation, inspiration, encouragement, positivity, energy, community, connection, commitment, collaboration, growth, impact, difference, success, progress, change, education, volunteering, veterans, homeless, shelter, meeting, project, system, process, event
- Generic categories (even capitalized): Users, Customers, Team, Family, Kids, Veterans, Community
- Abstract concepts: motivation, inspiration, gratitude, commitment, resilience
-
-THE TEST: Is this a specific name you'd find in a contact list or org chart?
- "John" → YES (promote=true)
- "kids" → NO (promote=false)
- "community" → NO (promote=false)
-
-When in doubt, set promote=false."""
-
-    try:
-        result = await llm_config.call(
-            messages=[
-                {"role": "system", "content": get_mission_filter_system_message()},
-                {"role": "user", "content": prompt},
-            ],
-            response_format=MissionFilterResponse,
-            scope="mental_model_emergent_evaluation",
-        )
-
-        # Build name -> promote map
-        promote_map = {c.name: c.promote for c in result.candidates}
-
-        # Find models to remove
-        models_to_remove = []
-        for model in models:
-            name = model["name"]
-            if name in promote_map:
-                if not promote_map[name]:
-                    models_to_remove.append(model["id"])
-                else:
-                    logger.debug(f"[EMERGENT] Keeping '{name}'")
-            else:
-                # Model not in response - remove to be safe
-                logger.info(f"[EMERGENT] '{name}' not in evaluation response, marking for removal")
-                models_to_remove.append(model["id"])
-
-        logger.info(f"[EMERGENT] Evaluation: {len(models_to_remove)}/{len(models)} emergent models marked for removal")
-        return models_to_remove
-
-    except Exception as e:
-        logger.warning(f"[EMERGENT] Evaluation failed, keeping all models: {e}")
-        return []
-
-
-async def detect_entity_candidates(
-    pool,
-    bank_id: str,
-    min_mentions: int = 5,
-    top_percent: int = 20,
-) -> list[EmergentCandidate]:
-    """
-    Detect entities that are candidates for promotion to mental models.
-
-    Args:
-        pool: Database connection pool
-        bank_id: Bank identifier
-        min_mentions: Minimum mention count to consider
-        top_percent: Only consider top X% by mention count
-
-    Returns:
-        List of entity candidates
-    """
-    from ..db_utils import acquire_with_retry
-    from ..memory_engine import fq_table
-
-    candidates = []
-
-    async with acquire_with_retry(pool) as conn:
-        # Get entities that meet criteria and don't already have mental models
-        rows = await conn.fetch(
-            f"""
-            WITH ranked AS (
-                SELECT
-                    e.id,
-                    e.canonical_name,
-                    e.mention_count,
-                    PERCENT_RANK() OVER (ORDER BY e.mention_count DESC) as rank_pct
-                FROM {fq_table("entities")} e
-                LEFT JOIN {fq_table("mental_models")} mm
-                    ON mm.entity_id = e.id AND mm.bank_id = e.bank_id
-                WHERE e.bank_id = $1
-                  AND e.mention_count >= $2
-                  AND mm.id IS NULL  -- Not already a mental model
-            )
-            SELECT id, canonical_name, mention_count
-            FROM ranked
-            WHERE rank_pct <= $3
-            ORDER BY mention_count DESC
-            LIMIT 50
-            """,
-            bank_id,
-            min_mentions,
-            top_percent / 100.0,
-        )
-
-        for row in rows:
-            candidates.append(
-                EmergentCandidate(
-                    name=row["canonical_name"],
-                    detection_method="named_entity_extraction",
-                    mention_count=row["mention_count"],
-                    entity_id=str(row["id"]),
-                    relevance_score=0.0,
-                )
-            )
-
-    logger.debug(f"[EMERGENT] Detected {len(candidates)} entity candidates")
-    return candidates
@@ -1,98 +0,0 @@
-"""
-Pydantic models for mental models.
-"""
-
-from datetime import datetime, timezone
-from enum import Enum
-
-from pydantic import BaseModel, Field
-
-
-class MentalModelSubtype(str, Enum):
-    """Subtype of mental model - how it was created."""
-
-    STRUCTURAL = "structural"  # Derived from mission, created upfront
-    EMERGENT = "emergent"  # Discovered from data patterns
-    LEARNED = "learned"  # Formed through reflection
-    PINNED = "pinned"  # User-defined topic, observations LLM-generated
-    DIRECTIVE = "directive"  # User-defined hard rules, observations user-provided
-
-
-class MentalModel(BaseModel):
-    """
-    A mental model representing synthesized understanding.
-
-    Mental models are the agent's consolidated knowledge. Unlike raw facts,
-    mental models provide:
-    - A one-liner description for quick scanning/retrieval
-    - A full summary for deep understanding
-    - Links to related mental models
-    """
-
-    id: str = Field(description="Unique identifier within the bank")
-    bank_id: str = Field(description="Bank this mental model belongs to")
-    subtype: MentalModelSubtype = Field(description="How this model was created")
-    name: str = Field(description="Human-readable name")
-    description: str = Field(description="One-liner for quick scanning and retrieval matching")
-    summary: str | None = Field(default=None, description="Full synthesized understanding")
-
-    # References
-    entity_id: str | None = Field(default=None, description="Reference to entities table when type=entity")
-    source_facts: list[str] = Field(default_factory=list, description="Fact IDs used to generate summary")
-    links: list[str] = Field(default_factory=list, description="Related mental model IDs")
-
-    # Tags for scoped visibility (similar to document tags)
-    tags: list[str] = Field(default_factory=list, description="Tags for scoped visibility filtering")
-
-    # Timestamps
-    last_updated: datetime | None = Field(default=None, description="When summary was last regenerated")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc), description="When this model was created"
-    )
-
-
-class StructuralModelTemplate(BaseModel):
-    """
-    A template for a structural mental model.
-
-    Generated by LLM based on the bank's mission. Represents what any agent
-    with this role would need to track.
-    """
-
-    id: str = Field(default="", description="Existing model ID to keep, or empty for new models")
-    name: str = Field(description="Human-readable name")
-    description: str = Field(description="What this model should track")
-    initial_probes: list[str] = Field(default_factory=list, description="Initial search queries to populate this model")
-
-
-class StructuralModelDerivationResponse(BaseModel):
-    """Response from LLM for structural model derivation."""
-
-    templates: list[StructuralModelTemplate] = Field(description="Structural model templates derived from the mission")
-
-
-class EmergentCandidate(BaseModel):
-    """
-    A candidate for promotion to emergent mental model.
-
-    Detected through pattern analysis of facts.
-    """
-
-    name: str = Field(description="Name of the detected pattern/entity")
-    detection_method: str = Field(description="How this candidate was detected")
-    mention_count: int = Field(default=0, description="How many times referenced")
-    entity_id: str | None = Field(default=None, description="Entity ID if detected as entity")
-    relevance_score: float = Field(default=0.0, description="Score from mission filter (0-1)")
-
-
-class ResearchResult(BaseModel):
-    """
-    Result from the research endpoint.
-
-    Contains the answer along with the mental models and facts used.
-    """
-
-    answer: str = Field(description="The synthesized answer")
-    mental_models_used: list[str] = Field(default_factory=list, description="IDs of mental models that contributed")
-    facts_used: list[str] = Field(default_factory=list, description="Fact IDs that contributed")
-    question_type: str | None = Field(default=None, description="Detected question type (WHO, WHAT, HOW, etc.)")
@@ -1,228 +0,0 @@
-"""
-Structural mental model derivation from bank mission.
-
-Structural models are derived from the bank's mission - they represent what
-any agent with this role would need to track. For example:
-
-Mission: "Be a PM for engineering team"
-Structural models:
-  - Team Structure (who's on the team, roles)
-  - Project Overview (current projects, status)
-  - Processes (how releases work, how decisions are made)
-  - Key Systems (what we own, dependencies)
-"""
-
-import logging
-from typing import TYPE_CHECKING
-
-from pydantic import BaseModel, Field
-
-from .models import StructuralModelTemplate
-
-if TYPE_CHECKING:
-    from ..llm_wrapper import LLMConfig
-
-logger = logging.getLogger(__name__)
-
-
-class StructuralDerivationResponse(BaseModel):
-    """Response from LLM for structural model derivation."""
-
-    templates: list[StructuralModelTemplate] = Field(description="Structural model templates derived from the mission")
-
-
-class StructuralRelevanceResult(BaseModel):
-    """Result of evaluating a structural model's relevance to the mission."""
-
-    name: str
-    relevant: bool
-    reason: str
-
-
-class StructuralRelevanceResponse(BaseModel):
-    """Response from LLM for structural model relevance evaluation."""
-
-    models: list[StructuralRelevanceResult] = Field(description="Relevance evaluation for each model")
-
-
-def build_structural_derivation_prompt(mission: str, existing_models: list[dict] | None = None) -> str:
-    """Build the prompt for deriving structural models from a mission."""
-    existing_section = ""
-    if existing_models:
-        model_list = "\n".join([f"- id='{m['id']}' name='{m['name']}': {m['description']}" for m in existing_models])
-        existing_section = f"""
-EXISTING STRUCTURAL MODELS:
-{model_list}
-
-IMPORTANT: If keeping an existing model, you MUST return its EXACT 'id' value.
-Models not included in your output will be REMOVED.
-"""
-
-    return f"""Given this agent mission, identify the KEY THINGS to track to achieve it.
-
-MISSION: {mission}
-{existing_section}
-IMPORTANT CONSTRAINTS:
- Return 0-3 structural models MAXIMUM (less is better!)
- Only include models for SPECIFIC, CONCRETE things the agent needs to track
- Each model must be DIRECTLY tied to achieving the mission
- If the mission is simple, return 0 models (empty array is fine)
- If existing models are provided and you want to keep one, use its EXACT id
- Do NOT create near-duplicates (e.g., don't create "topic-map" if "topic-connections" exists)
-
-GOOD examples (specific, actionable):
- Mission: "Be a PM for engineering team" → "Team Members" (track who's on the team)
- Mission: "Track customer feedback" → "Customer Issues" (track specific complaints/requests)
- Mission: "Manage project X" → "Project X Milestones" (track progress)
-
-BAD examples (too generic, don't create these):
- "Processes", "Workflows", "Key Systems", "Important Events"
- "Communication", "Collaboration", "Progress", "Status"
- Generic role-based models not tied to the specific mission
-
-For each model:
-1. id: Use EXACT existing id if keeping a model, or leave empty for new models
-2. name: Short, specific name (e.g., "Team Members", "Sprint Goals")
-3. description: One line describing what to track
-4. initial_probes: 2-3 search queries to find relevant information
-
-Return ONLY the models that should exist. Existing models not in your output will be deleted."""
-
-
-def get_structural_derivation_system_message() -> str:
-    """System message for structural model derivation."""
-    return """You identify the key things to track for a mission. Be VERY selective.
-
-Rules:
- Maximum 3 models (prefer fewer)
- Only SPECIFIC, CONCRETE things - not generic categories
- Each must DIRECTLY help achieve the mission
- Empty array is valid if no models are truly needed
- If existing models are shown and you want to keep one, return its EXACT id
- Never create duplicates - if a similar model exists, keep the existing one
-
-Output JSON with 'templates' array (can be empty)."""
-
-
-def _normalize_id(text: str) -> str:
-    """Normalize a string to a canonical form for comparison.
-
-    Removes common suffixes, pluralization, and normalizes separators.
-    """
-    # Lowercase and normalize separators
-    normalized = text.lower().replace(" ", "-").replace("_", "-")
-
-    # Remove common suffixes that indicate the same concept
-    suffixes_to_remove = ["-map", "-list", "-overview", "-tracker", "-s"]
-    for suffix in suffixes_to_remove:
-        if normalized.endswith(suffix) and len(normalized) > len(suffix):
-            normalized = normalized[: -len(suffix)]
-
-    return normalized
-
-
-def _find_similar_existing_id(new_id: str, existing_models: list[dict]) -> str | None:
-    """Find an existing model ID that is similar to the new ID.
-
-    Returns the existing ID if a similar one is found, None otherwise.
-    """
-    if not existing_models:
-        return None
-
-    new_normalized = _normalize_id(new_id)
-
-    for model in existing_models:
-        existing_id = model.get("id", "")
-        existing_normalized = _normalize_id(existing_id)
-
-        # Check if one is a prefix of the other (normalized)
-        if new_normalized.startswith(existing_normalized) or existing_normalized.startswith(new_normalized):
-            return existing_id
-
-        # Check if they're the same when normalized
-        if new_normalized == existing_normalized:
-            return existing_id
-
-    return None
-
-
-async def derive_structural_models(
-    llm_config: "LLMConfig",
-    mission: str,
-    existing_models: list[dict] | None = None,
-) -> tuple[list[StructuralModelTemplate], list[str]]:
-    """
-    Derive structural model templates from a bank's mission.
-
-    This combines derivation and evaluation in one call. The LLM sees existing
-    models and decides which to keep. Any existing model not in the output
-    will be marked for removal.
-
-    Args:
-        llm_config: LLM configuration for calling the model
-        mission: The bank's mission (e.g., "Be a PM for engineering team")
-        existing_models: Optional list of existing model dicts with 'name', 'description', 'id'
-
-    Returns:
-        Tuple of (templates to create/keep, IDs of existing models to remove)
-
-    Raises:
-        Exception: If LLM call fails
-    """
-    prompt = build_structural_derivation_prompt(mission, existing_models)
-
-    result = await llm_config.call(
-        messages=[
-            {"role": "system", "content": get_structural_derivation_system_message()},
-            {"role": "user", "content": prompt},
-        ],
-        response_format=StructuralDerivationResponse,
-        scope="mental_model_structural_derivation",
-    )
-
-    templates = result.templates
-    logger.info(f"[STRUCTURAL] LLM returned {len(templates)} structural models")
-
-    # Build set of existing IDs for quick lookup
-    existing_ids = {m["id"] for m in existing_models} if existing_models else set()
-
-    # Process templates: validate IDs, deduplicate, assign stable IDs
-    processed_templates: list[StructuralModelTemplate] = []
-    kept_existing_ids: set[str] = set()
-
-    for template in templates:
-        # If LLM returned an ID, check if it's a valid existing ID
-        if template.id and template.id in existing_ids:
-            # LLM is keeping an existing model
-            kept_existing_ids.add(template.id)
-            processed_templates.append(template)
-            logger.info(f"[STRUCTURAL] Keeping existing model: {template.id}")
-        else:
-            # New model or LLM didn't return a valid ID
-            # Generate ID from name
-            generated_id = template.name.lower().replace(" ", "-").replace("_", "-")
-
-            # Check for similar existing models to prevent near-duplicates
-            similar_id = _find_similar_existing_id(generated_id, existing_models)
-            if similar_id and similar_id not in kept_existing_ids:
-                # Use the existing similar model instead of creating a new one
-                logger.info(f"[STRUCTURAL] Detected near-duplicate: '{generated_id}' matches existing '{similar_id}'")
-                template.id = similar_id
-                kept_existing_ids.add(similar_id)
-            else:
-                template.id = generated_id
-
-            processed_templates.append(template)
-
-    # Find existing models to remove (not kept in LLM output)
-    models_to_remove = []
-    if existing_models:
-        for model in existing_models:
-            if model["id"] not in kept_existing_ids:
-                logger.info(f"[STRUCTURAL] Marking '{model['name']}' (id={model['id']}) for removal")
-                models_to_remove.append(model["id"])
-
-    if models_to_remove:
-        logger.info(f"[STRUCTURAL] {len(models_to_remove)} existing models will be removed")
-
-    return processed_templates, models_to_remove
@@ -84,7 +84,7 @@ class DateparserQueryAnalyzer(QueryAnalyzer):

    Performance:
    - ~10-50ms per query
-    - No model loading required (lazy import on first use)
+    - No model loading required
    """

    def __init__(self):
@@ -112,6 +112,8 @@ class DateparserQueryAnalyzer(QueryAnalyzer):
        Returns:
            QueryAnalysis with temporal_constraint if found
        """
+        self.load()
+
        if reference_date is None:
            reference_date = datetime.now()

@@ -121,9 +123,6 @@ class DateparserQueryAnalyzer(QueryAnalyzer):
        if period_result is not None:
            return QueryAnalysis(temporal_constraint=period_result)

-        # Lazy load dateparser (only imports on first call, then cached)
-        self.load()
-
        # Use dateparser's search_dates to find temporal expressions
        settings = {
            "RELATIVE_BASE": reference_date,
@@ -1,20 +0,0 @@
-"""
-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. Learn new insights (create/update mental models)
-4. Expand memories (get chunk/document context)
-"""
-
-from .agent import ReflectAgentResult, run_reflect_agent
-from .models import MentalModelInput, ReflectAction, ReflectActionBatch
-
-__all__ = [
-    "run_reflect_agent",
-    "ReflectAgentResult",
-    "ReflectAction",
-    "ReflectActionBatch",
-    "MentalModelInput",
-]
@@ -1,723 +0,0 @@
-"""
-Reflect agent - agentic loop for reflection with native tool calling.
-"""
-
-import asyncio
-import json
-import logging
-import time
-from typing import TYPE_CHECKING, Any, Awaitable, Callable
-
-from .models import DirectiveInfo, LLMCall, MentalModelInput, ReflectAgentResult, ToolCall
-from .prompts import FINAL_SYSTEM_PROMPT, _extract_directive_rules, build_final_prompt, build_system_prompt_for_tools
-from .tools_schema import get_reflect_tools
-
-
-def _build_directives_applied(directives: list[dict[str, Any]] | None) -> list[DirectiveInfo]:
-    """Build list of DirectiveInfo from directive mental models."""
-    if not directives:
-        return []
-
-    result = []
-    for directive in directives:
-        directive_id = directive.get("id", "")
-        directive_name = directive.get("name", "")
-        observations = directive.get("observations", [])
-
-        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, rules=rules))
-
-    return result
-
-
-if TYPE_CHECKING:
-    from ..llm_wrapper import LLMProvider
-    from ..response_models import LLMToolCall
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_MAX_ITERATIONS = 10
-
-
-async def _generate_structured_output(
-    answer: str,
-    response_schema: dict,
-    llm_config: "LLMProvider",
-    reflect_id: str,
-) -> dict[str, Any] | None:
-    """Generate structured output from an answer using the provided JSON schema.
-
-    Args:
-        answer: The text answer to extract structured data from
-        response_schema: JSON Schema for the expected output structure
-        llm_config: LLM provider for making the extraction call
-        reflect_id: Reflect ID for logging
-
-    Returns:
-        Structured output dict if successful, None otherwise
-    """
-    try:
-        from typing import Any as TypingAny
-
-        from pydantic import create_model
-
-        def _json_schema_type_to_python(field_schema: dict) -> type:
-            """Map JSON schema type to Python type for better LLM guidance."""
-            json_type = field_schema.get("type", "string")
-            if json_type == "array":
-                return list
-            elif json_type == "object":
-                return dict
-            elif json_type == "integer":
-                return int
-            elif json_type == "number":
-                return float
-            elif json_type == "boolean":
-                return bool
-            else:
-                return str
-
-        # Build fields from JSON schema properties
-        schema_props = response_schema.get("properties", {})
-        required_fields = set(response_schema.get("required", []))
-        fields: dict[str, TypingAny] = {}
-        for field_name, field_schema in schema_props.items():
-            field_type = _json_schema_type_to_python(field_schema)
-            default = ... if field_name in required_fields else None
-            fields[field_name] = (field_type, default)
-
-        if not fields:
-            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)
-
-        # Call LLM with the answer to extract structured data
-        structured_prompt = f"""Based on this answer, extract the information into the requested structured format.
-
-Answer: {answer}
-
-JSON Schema to follow:
-```json
-{schema_str}
-```
-
-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
-
-Do not include any explanation, only the JSON object."""
-
-        structured_result = await llm_config.call(
-            messages=[
-                {
-                    "role": "system",
-                    "content": "Extract structured data from the given answer. Return only valid JSON matching the provided schema exactly.",
-                },
-                {"role": "user", "content": structured_prompt},
-            ],
-            response_format=DynamicModel,
-            scope="reflect_structured",
-            skip_validation=True,  # We'll handle the dict ourselves
-        )
-
-        # Convert to dict
-        if hasattr(structured_result, "model_dump"):
-            structured_output = structured_result.model_dump()
-        elif isinstance(structured_result, dict):
-            structured_output = structured_result
-        else:
-            # Try to parse as JSON
-            structured_output = json.loads(str(structured_result))
-
-        logger.info(f"[REFLECT {reflect_id}] Generated structured output with {len(structured_output)} fields")
-        return structured_output
-
-    except Exception as e:
-        logger.warning(f"[REFLECT {reflect_id}] Failed to generate structured output: {e}")
-        return None
-
-
-async def run_reflect_agent(
-    llm_config: "LLMProvider",
-    bank_id: str,
-    query: str,
-    bank_profile: dict[str, Any],
-    lookup_fn: Callable[[str | None], Awaitable[dict[str, Any]]],
-    recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
-    learn_fn: Callable[[MentalModelInput], Awaitable[dict[str, Any]]] | None = None,
-    context: str | None = None,
-    max_iterations: int = DEFAULT_MAX_ITERATIONS,
-    max_tokens: int | None = None,
-    response_schema: dict | None = None,
-    directives: list[dict[str, Any]] | None = None,
-) -> ReflectAgentResult:
-    """
-    Execute the reflect agent loop using native tool calling.
-
-    The agent iteratively calls tools to gather information and learn,
-    then provides a final answer via the done() tool.
-
-    Args:
-        llm_config: LLM provider for agent calls
-        bank_id: Bank identifier
-        query: Question to answer
-        bank_profile: Bank profile with name and mission
-        lookup_fn: Tool callback for lookup (model_id) -> result
-        recall_fn: Tool callback for recall (query, max_tokens) -> result
-        expand_fn: Tool callback for expand (memory_id, depth) -> result
-        learn_fn: Optional tool callback for learn (MentalModelInput) -> result.
-                  If None, learn tool is disabled.
-        context: Optional additional context
-        max_iterations: Maximum number of iterations before forcing response
-        max_tokens: Maximum tokens for the final response
-        response_schema: Optional JSON Schema for structured output in final response
-        directives: Optional list of directive mental models to inject as hard rules
-
-    Returns:
-        ReflectAgentResult with final answer and metadata
-    """
-    enable_learn = learn_fn is not None
-    reflect_id = f"{bank_id[:8]}-{int(time.time() * 1000) % 100000}"
-    start_time = time.time()
-
-    # Build directives_applied for the trace
-    directives_applied = _build_directives_applied(directives)
-
-    # Extract directive rules for tool schema (if any)
-    directive_rules = _extract_directive_rules(directives) if directives else None
-
-    # Get tools for this agent (with directive compliance field if directives exist)
-    tools = get_reflect_tools(enable_learn=enable_learn, 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)
-    messages: list[dict[str, Any]] = [
-        {"role": "system", "content": system_prompt},
-        {"role": "user", "content": query},
-    ]
-
-    # Tracking
-    mental_models_created: list[str] = []
-    total_tools_called = 0
-    tool_trace: list[ToolCall] = []
-    tool_trace_summary: list[dict[str, Any]] = []
-    llm_trace: list[dict[str, Any]] = []
-    context_history: list[dict[str, Any]] = []  # For final prompt fallback
-
-    # Track available IDs for validation (prevents hallucinated citations)
-    available_memory_ids: set[str] = set()
-    available_model_ids: set[str] = set()
-
-    # Pre-fetch mental models so the agent always starts with this knowledge
-    prefetch_start = time.time()
-    models_result = await lookup_fn(None)  # List all mental models
-    prefetch_duration = int((time.time() - prefetch_start) * 1000)
-
-    # Track available model IDs
-    if isinstance(models_result, dict) and "models" in models_result:
-        for model in models_result["models"]:
-            if "id" in model:
-                available_model_ids.add(model["id"])
-
-    # Add to context history for the agent
-    context_history.append({"tool": "list_mental_models", "output": models_result})
-
-    # Add to tool trace
-    tool_trace.append(
-        ToolCall(
-            tool="list_mental_models",
-            input={"tool": "list_mental_models"},
-            output=models_result,
-            duration_ms=prefetch_duration,
-            iteration=0,
-        )
-    )
-    tool_trace_summary.append(
-        {
-            "tool": "list_mental_models",
-            "input_summary": "(prefetch)",
-            "duration_ms": prefetch_duration,
-            "output_chars": len(json.dumps(models_result, default=str)),
-        }
-    )
-    total_tools_called += 1
-
-    # Include in the user message so the agent sees it
-    models_info = json.dumps(models_result, indent=2, default=str)
-    messages[1]["content"] = f"{query}\n\n## Available Mental Models (pre-fetched)\n```json\n{models_info}\n```"
-
-    def _get_llm_trace() -> list[LLMCall]:
-        return [LLMCall(scope=c["scope"], duration_ms=c["duration_ms"]) for c in llm_trace]
-
-    def _log_completion(answer: str, iterations: int, forced: bool = False):
-        elapsed_ms = int((time.time() - start_time) * 1000)
-        tools_summary = (
-            ", ".join(
-                f"{t['tool']}({t['input_summary']})={t['duration_ms']}ms/{t.get('output_chars', 0)}c"
-                for t in tool_trace_summary
-            )
-            or "none"
-        )
-        llm_summary = ", ".join(f"{c['scope']}={c['duration_ms']}ms" for c in llm_trace) or "none"
-        total_llm_ms = sum(c["duration_ms"] for c in llm_trace)
-        total_tools_ms = sum(t["duration_ms"] for t in tool_trace_summary)
-
-        answer_preview = answer[:100] + "..." if len(answer) > 100 else answer
-        mode = "forced" if forced else "done"
-        logger.info(
-            f"[REFLECT {reflect_id}] {mode} | "
-            f"query='{query[:50]}...' | "
-            f"iterations={iterations} | "
-            f"llm=[{llm_summary}] ({total_llm_ms}ms) | "
-            f"tools=[{tools_summary}] ({total_tools_ms}ms) | "
-            f"answer='{answer_preview}' | "
-            f"total={elapsed_ms}ms"
-        )
-
-    for iteration in range(max_iterations):
-        is_last = iteration == max_iterations - 1
-
-        if is_last:
-            # Force text response on last iteration - no tools
-            prompt = build_final_prompt(query, context_history, bank_profile, context)
-            llm_start = time.time()
-            response = await llm_config.call(
-                messages=[
-                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
-                    {"role": "user", "content": prompt},
-                ],
-                scope="reflect_agent_final",
-                max_completion_tokens=max_tokens,
-            )
-            llm_trace.append({"scope": "final", "duration_ms": int((time.time() - llm_start) * 1000)})
-            answer = response.strip()
-
-            # Generate structured output if schema provided
-            structured_output = None
-            if response_schema and answer:
-                structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
-
-            _log_completion(answer, iteration + 1, forced=True)
-            return ReflectAgentResult(
-                text=answer,
-                structured_output=structured_output,
-                iterations=iteration + 1,
-                tools_called=total_tools_called,
-                mental_models_created=mental_models_created,
-                tool_trace=tool_trace,
-                llm_trace=_get_llm_trace(),
-                directives_applied=directives_applied,
-            )
-
-        # Call LLM with tools
-        llm_start = time.time()
-
-        try:
-            result = await llm_config.call_with_tools(
-                messages=messages,
-                tools=tools,
-                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)
-            llm_trace.append({"scope": f"agent_{iteration + 1}", "duration_ms": llm_duration})
-
-        except Exception:
-            llm_trace.append(
-                {"scope": f"agent_{iteration + 1}_err", "duration_ms": int((time.time() - llm_start) * 1000)}
-            )
-            # Guardrail: If no evidence gathered yet, retry
-            has_gathered_evidence = bool(available_memory_ids) or bool(available_model_ids)
-            if not has_gathered_evidence and iteration < max_iterations - 1:
-                continue
-            prompt = build_final_prompt(query, context_history, bank_profile, context)
-            llm_start = time.time()
-            response = await llm_config.call(
-                messages=[
-                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
-                    {"role": "user", "content": prompt},
-                ],
-                scope="reflect_agent_final",
-                max_completion_tokens=max_tokens,
-            )
-            llm_trace.append({"scope": "final", "duration_ms": int((time.time() - llm_start) * 1000)})
-            answer = response.strip()
-
-            # Generate structured output if schema provided
-            structured_output = None
-            if response_schema and answer:
-                structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
-
-            _log_completion(answer, iteration + 1, forced=True)
-            return ReflectAgentResult(
-                text=answer,
-                structured_output=structured_output,
-                iterations=iteration + 1,
-                tools_called=total_tools_called,
-                mental_models_created=mental_models_created,
-                tool_trace=tool_trace,
-                llm_trace=_get_llm_trace(),
-                directives_applied=directives_applied,
-            )
-
-        # No tool calls - LLM wants to respond with text
-        if not result.tool_calls:
-            if result.content:
-                answer = result.content.strip()
-
-                # Generate structured output if schema provided
-                structured_output = None
-                if response_schema and answer:
-                    structured_output = await _generate_structured_output(
-                        answer, response_schema, llm_config, reflect_id
-                    )
-
-                _log_completion(answer, iteration + 1)
-                return ReflectAgentResult(
-                    text=answer,
-                    structured_output=structured_output,
-                    iterations=iteration + 1,
-                    tools_called=total_tools_called,
-                    mental_models_created=mental_models_created,
-                    tool_trace=tool_trace,
-                    llm_trace=_get_llm_trace(),
-                    directives_applied=directives_applied,
-                )
-            # Empty response, force final
-            prompt = build_final_prompt(query, context_history, bank_profile, context)
-            llm_start = time.time()
-            response = await llm_config.call(
-                messages=[
-                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
-                    {"role": "user", "content": prompt},
-                ],
-                scope="reflect_agent_final",
-                max_completion_tokens=max_tokens,
-            )
-            llm_trace.append({"scope": "final", "duration_ms": int((time.time() - llm_start) * 1000)})
-            answer = response.strip()
-
-            # Generate structured output if schema provided
-            structured_output = None
-            if response_schema and answer:
-                structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
-
-            _log_completion(answer, iteration + 1, forced=True)
-            return ReflectAgentResult(
-                text=answer,
-                structured_output=structured_output,
-                iterations=iteration + 1,
-                tools_called=total_tools_called,
-                mental_models_created=mental_models_created,
-                tool_trace=tool_trace,
-                llm_trace=_get_llm_trace(),
-                directives_applied=directives_applied,
-            )
-
-        # Check for done tool call (handle both 'done' and 'functions.done')
-        done_call = next((tc for tc in result.tool_calls if tc.name == "done" or tc.name == "functions.done"), None)
-        if done_call:
-            # Guardrail: Require evidence before done
-            has_gathered_evidence = bool(available_memory_ids) or bool(available_model_ids)
-            if not has_gathered_evidence and iteration < max_iterations - 1:
-                # Add assistant message and fake tool result asking for evidence
-                messages.append(
-                    {
-                        "role": "assistant",
-                        "tool_calls": [_tool_call_to_dict(done_call)],
-                    }
-                )
-                messages.append(
-                    {
-                        "role": "tool",
-                        "tool_call_id": done_call.id,
-                        "content": json.dumps(
-                            {
-                                "error": "You must call recall() or list_mental_models() to gather evidence before providing your final answer."
-                            }
-                        ),
-                    }
-                )
-                continue
-
-            # Process done tool
-            return await _process_done_tool(
-                done_call,
-                available_memory_ids,
-                available_model_ids,
-                iteration + 1,
-                total_tools_called,
-                mental_models_created,
-                tool_trace,
-                _get_llm_trace(),
-                _log_completion,
-                reflect_id,
-                directives_applied=directives_applied,
-                llm_config=llm_config,
-                response_schema=response_schema,
-            )
-
-        # Execute other tools in parallel (exclude done and functions.done)
-        other_tools = [tc for tc in result.tool_calls if tc.name not in ("done", "functions.done")]
-        if other_tools:
-            # Add assistant message with tool calls
-            messages.append(
-                {
-                    "role": "assistant",
-                    "tool_calls": [_tool_call_to_dict(tc) for tc in other_tools],
-                }
-            )
-
-            # Execute tools in parallel
-            tool_tasks = [
-                _execute_tool_with_timing(tc, lookup_fn, recall_fn, expand_fn, learn_fn) for tc in other_tools
-            ]
-            tool_results = await asyncio.gather(*tool_tasks, return_exceptions=True)
-            total_tools_called += len(other_tools)
-
-            # Process results and add to messages
-            for tc, result_data in zip(other_tools, tool_results):
-                if isinstance(result_data, Exception):
-                    # Tool execution failed - log and raise to fail the request
-                    logger.error(f"[REFLECT {reflect_id}] Tool {tc.name} failed with exception: {result_data}")
-                    raise RuntimeError(f"Reflect tool '{tc.name}' failed: {result_data}")
-
-                output, duration_ms = result_data
-
-                # Check if tool returned an error response
-                if isinstance(output, dict) and "error" in output:
-                    logger.error(f"[REFLECT {reflect_id}] Tool {tc.name} returned error: {output['error']}")
-                    raise RuntimeError(f"Reflect tool '{tc.name}' error: {output['error']}")
-
-                # Track created mental models
-                if tc.name == "learn" and isinstance(output, dict) and "model_id" in output:
-                    mental_models_created.append(output["model_id"])
-
-                # Track available memory IDs from recall
-                if tc.name == "recall" and isinstance(output, dict) and "memories" in output:
-                    for memory in output["memories"]:
-                        if "id" in memory:
-                            available_memory_ids.add(memory["id"])
-
-                # Track available model IDs
-                if tc.name in ("list_mental_models", "get_mental_model") and isinstance(output, dict):
-                    if output.get("found") and "model" in output:
-                        model_id = output["model"].get("id")
-                        if model_id:
-                            available_model_ids.add(model_id)
-                    elif "models" in output:
-                        for model in output["models"]:
-                            if "id" in model:
-                                available_model_ids.add(model["id"])
-
-                # Add tool result message
-                messages.append(
-                    {
-                        "role": "tool",
-                        "tool_call_id": tc.id,
-                        "content": json.dumps(output, default=str),
-                    }
-                )
-
-                # Track for logging and context history
-                input_dict = {"tool": tc.name, **tc.arguments}
-                input_summary = _summarize_input(tc.name, tc.arguments)
-
-                tool_trace.append(
-                    ToolCall(
-                        tool=tc.name, input=input_dict, output=output, duration_ms=duration_ms, iteration=iteration + 1
-                    )
-                )
-
-                try:
-                    output_chars = len(json.dumps(output))
-                except (TypeError, ValueError):
-                    output_chars = len(str(output))
-
-                tool_trace_summary.append(
-                    {
-                        "tool": tc.name,
-                        "input_summary": input_summary,
-                        "duration_ms": duration_ms,
-                        "output_chars": output_chars,
-                    }
-                )
-
-                # Keep context history for fallback final prompt
-                context_history.append({"tool": tc.name, "input": input_dict, "output": output})
-
-    # Should not reach here
-    answer = "I was unable to formulate a complete answer within the iteration limit."
-    _log_completion(answer, max_iterations, forced=True)
-    return ReflectAgentResult(
-        text=answer,
-        iterations=max_iterations,
-        tools_called=total_tools_called,
-        mental_models_created=mental_models_created,
-        tool_trace=tool_trace,
-        llm_trace=_get_llm_trace(),
-        directives_applied=directives_applied,
-    )
-
-
-def _tool_call_to_dict(tc: "LLMToolCall") -> dict[str, Any]:
-    """Convert LLMToolCall to OpenAI message format."""
-    return {
-        "id": tc.id,
-        "type": "function",
-        "function": {
-            "name": tc.name,
-            "arguments": json.dumps(tc.arguments),
-        },
-    }
-
-
-async def _process_done_tool(
-    done_call: "LLMToolCall",
-    available_memory_ids: set[str],
-    available_model_ids: set[str],
-    iterations: int,
-    total_tools_called: int,
-    mental_models_created: list[str],
-    tool_trace: list[ToolCall],
-    llm_trace: list[LLMCall],
-    log_completion: Callable,
-    reflect_id: str,
-    directives_applied: list[DirectiveInfo],
-    llm_config: "LLMProvider | None" = None,
-    response_schema: dict | None = None,
-) -> ReflectAgentResult:
-    """Process the done tool call and return the result."""
-    args = done_call.arguments
-
-    answer = args.get("answer", "").strip()
-    if not answer:
-        answer = "No answer provided."
-
-    # Validate IDs
-    used_memory_ids = [mid for mid in args.get("memory_ids", []) if mid in available_memory_ids]
-    used_model_ids = [mid for mid in args.get("model_ids", []) if mid in available_model_ids]
-
-    # Generate structured output if schema provided
-    structured_output = None
-    if response_schema and llm_config and answer:
-        structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
-
-    log_completion(answer, iterations)
-    return ReflectAgentResult(
-        text=answer,
-        structured_output=structured_output,
-        iterations=iterations,
-        tools_called=total_tools_called,
-        mental_models_created=mental_models_created,
-        tool_trace=tool_trace,
-        llm_trace=llm_trace,
-        used_memory_ids=used_memory_ids,
-        used_model_ids=used_model_ids,
-        directives_applied=directives_applied,
-    )
-
-
-async def _execute_tool_with_timing(
-    tc: "LLMToolCall",
-    lookup_fn: Callable[[str | None], Awaitable[dict[str, Any]]],
-    recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
-    learn_fn: Callable[[MentalModelInput], Awaitable[dict[str, Any]]] | None = None,
-) -> tuple[dict[str, Any], int]:
-    """Execute a tool call and return result with timing."""
-    start = time.time()
-    result = await _execute_tool(tc.name, tc.arguments, lookup_fn, recall_fn, expand_fn, learn_fn)
-    duration_ms = int((time.time() - start) * 1000)
-    return result, duration_ms
-
-
-async def _execute_tool(
-    tool_name: str,
-    args: dict[str, Any],
-    lookup_fn: Callable[[str | None], Awaitable[dict[str, Any]]],
-    recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
-    learn_fn: Callable[[MentalModelInput], Awaitable[dict[str, Any]]] | None = None,
-) -> dict[str, Any]:
-    """Execute a single tool by name."""
-    # Normalize tool name - some LLMs return 'functions.done' instead of 'done'
-    if tool_name.startswith("functions."):
-        tool_name = tool_name[len("functions.") :]
-
-    if tool_name == "list_mental_models":
-        return await lookup_fn(None)
-
-    elif tool_name == "get_mental_model":
-        model_id = args.get("model_id")
-        if not model_id:
-            return {"error": "get_mental_model requires model_id"}
-        return await lookup_fn(model_id)
-
-    elif tool_name == "recall":
-        query = args.get("query")
-        if not query:
-            return {"error": "recall requires a query parameter"}
-        max_tokens = max(args.get("max_tokens") or 2048, 1000)  # Default 2048, min 1000
-        return await recall_fn(query, max_tokens)
-
-    elif tool_name == "learn":
-        if learn_fn is None:
-            return {"error": "learn tool is not available"}
-        name = args.get("name")
-        description = args.get("description")
-        if not name or not description:
-            return {"error": "learn requires name and description"}
-        return await learn_fn(MentalModelInput(name=name, description=description))
-
-    elif tool_name == "expand":
-        memory_ids = args.get("memory_ids", [])
-        if not memory_ids:
-            return {"error": "expand requires memory_ids"}
-        depth = args.get("depth", "chunk")
-        return await expand_fn(memory_ids, depth)
-
-    else:
-        return {"error": f"Unknown tool: {tool_name}"}
-
-
-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 == "list_mental_models":
-        return "()"
-    elif tool_name == "get_mental_model":
-        return f"(model_id={args.get('model_id', '?')})"
-    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(args.get("max_tokens") or 2048, 1000)
-        return f"(query={query_preview}, max_tokens={max_tokens})"
-    elif tool_name == "learn":
-        name = args.get("name", "?")
-        desc = args.get("description", "")
-        desc_preview = f"'{desc[:20]}...'" if len(desc) > 20 else f"'{desc}'"
-        return f"(name='{name}', description={desc_preview})"
-    elif tool_name == "expand":
-        memory_ids = args.get("memory_ids", [])
-        depth = args.get("depth", "chunk")
-        return f"(memory_ids=[{len(memory_ids)} ids], depth={depth})"
-    elif tool_name == "done":
-        answer = args.get("answer", "")
-        answer_preview = f"'{answer[:30]}...'" if len(answer) > 30 else f"'{answer}'"
-        memory_ids = args.get("memory_ids", [])
-        model_ids = args.get("model_ids", [])
-        return f"(answer={answer_preview}, memory_ids={len(memory_ids)}, model_ids={len(model_ids)})"
-    return str(args)
@@ -1,114 +0,0 @@
-"""
-Pydantic models for the reflect agent.
-"""
-
-from typing import Any, Literal
-
-from pydantic import BaseModel, Field
-
-
-class MentalModelObservation(BaseModel):
-    """An observation within a mental model with its supporting memories."""
-
-    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_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
-    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")
-    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="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"
-    )
-    answer_model_ids: list[str] | None = Field(
-        default=None, description="Mental model IDs supporting the answer", alias="model_ids"
-    )
-    reasoning: str | None = Field(default=None, description="Brief reasoning for this action")
-
-
-class ReflectActionBatch(BaseModel):
-    """Batch of actions for parallel execution."""
-
-    actions: list[ReflectAction] = Field(description="List of actions to execute in parallel")
-
-
-class ToolCall(BaseModel):
-    """A single tool call made during reflect."""
-
-    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")
-    iteration: int = Field(default=0, description="Iteration number (1-based) when this tool was called")
-
-
-class LLMCall(BaseModel):
-    """A single LLM call made during reflect."""
-
-    scope: str = Field(description="Call scope: agent_1, agent_2, final, etc.")
-    duration_ms: int = Field(description="Execution time in milliseconds")
-
-
-class DirectiveInfo(BaseModel):
-    """Information about a directive that was applied during reflect."""
-
-    id: str = Field(description="Directive mental model ID")
-    name: str = Field(description="Directive name")
-    rules: list[str] = Field(default_factory=list, description="Directive rules/observations that were applied")
-
-
-class ReflectAgentResult(BaseModel):
-    """Result from the reflect agent."""
-
-    text: str = Field(description="Final answer text")
-    structured_output: dict[str, Any] | None = Field(
-        default=None, description="Structured output parsed according to provided response_schema"
-    )
-    iterations: int = Field(default=0, description="Number of iterations taken")
-    tools_called: int = Field(default=0, description="Total number of tool calls made")
-    mental_models_created: list[str] = Field(default_factory=list, description="IDs of mental models created/updated")
-    tool_trace: list[ToolCall] = Field(default_factory=list, description="Trace of all tool calls made")
-    llm_trace: list[LLMCall] = Field(default_factory=list, description="Trace of all LLM calls made")
-    used_memory_ids: list[str] = Field(default_factory=list, description="Validated memory IDs actually used in answer")
-    used_model_ids: list[str] = Field(default_factory=list, description="Validated model IDs actually used in answer")
-    directives_applied: list[DirectiveInfo] = Field(
-        default_factory=list, description="Directive mental models that affected this reflection"
-    )
@@ -1,248 +0,0 @@
-"""
-Models and utilities for evidence-grounded observations with computed trends.
-
-Observations are part of mental models and represent patterns/beliefs derived
-from memories. Each observation must be grounded in specific evidence (quotes)
-from memories, and trends are computed algorithmically from evidence timestamps.
-"""
-
-from datetime import datetime, timedelta, timezone
-from enum import Enum
-
-from pydantic import BaseModel, Field, computed_field, field_validator
-
-
-class Trend(str, Enum):
-    """Computed trend for an observation based on evidence timestamps.
-
-    Trends indicate how an observation's evidence is distributed over time:
-    - STABLE: Evidence spread across time, continues to present
-    - STRENGTHENING: More/denser evidence recently than before
-    - WEAKENING: Evidence mostly old, sparse recently
-    - NEW: All evidence within recent window
-    - STALE: No evidence in recent window (may no longer apply)
-    """
-
-    STABLE = "stable"
-    STRENGTHENING = "strengthening"
-    WEAKENING = "weakening"
-    NEW = "new"
-    STALE = "stale"
-
-
-class ObservationEvidence(BaseModel):
-    """A single piece of evidence supporting an observation.
-
-    Each evidence item must include an exact quote from the source memory
-    to ensure observations are grounded and verifiable.
-    """
-
-    memory_id: str = Field(description="ID of the memory unit this evidence comes from")
-    quote: str = Field(description="Exact quote from the memory supporting the observation")
-    relevance: str = Field(default="", description="Brief explanation of how this quote supports the observation")
-    timestamp: datetime = Field(description="When the source memory was created")
-
-    @field_validator("timestamp", mode="before")
-    @classmethod
-    def ensure_timezone_aware(cls, v: datetime | str | None) -> datetime:
-        """Ensure timestamp is always timezone-aware UTC."""
-        if v is None:
-            return datetime.now(timezone.utc)
-        if isinstance(v, str):
-            # Parse ISO format string, handling 'Z' suffix
-            v = datetime.fromisoformat(v.replace("Z", "+00:00"))
-        if isinstance(v, datetime):
-            if v.tzinfo is None:
-                return v.replace(tzinfo=timezone.utc)
-            return v
-        raise ValueError(f"Invalid timestamp type: {type(v)}")
-
-
-class Observation(BaseModel):
-    """A single observation within a mental model.
-
-    Observations represent patterns, preferences, beliefs, or other insights
-    derived from memories. Each observation must be grounded in evidence
-    with exact quotes from source memories.
-    """
-
-    title: str = Field(description="Short summary title for the observation (5-10 words)")
-    content: str = Field(description="The observation content - detailed explanation of what we believe to be true")
-    evidence: list[ObservationEvidence] = Field(default_factory=list, description="Supporting evidence with quotes")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc), description="When this observation was first created"
-    )
-
-    @field_validator("created_at", mode="before")
-    @classmethod
-    def ensure_created_at_timezone_aware(cls, v: datetime | str | None) -> datetime:
-        """Ensure created_at is always timezone-aware UTC."""
-        if v is None:
-            return datetime.now(timezone.utc)
-        if isinstance(v, str):
-            v = datetime.fromisoformat(v.replace("Z", "+00:00"))
-        if isinstance(v, datetime):
-            if v.tzinfo is None:
-                return v.replace(tzinfo=timezone.utc)
-            return v
-        raise ValueError(f"Invalid created_at type: {type(v)}")
-
-    @computed_field
-    @property
-    def trend(self) -> Trend:
-        """Compute trend from evidence timestamps."""
-        return compute_trend(self.evidence)
-
-    @computed_field
-    @property
-    def evidence_span(self) -> dict[str, str | None]:
-        """Get the time span covered by evidence."""
-        if not self.evidence:
-            return {"from": None, "to": None}
-        timestamps = [e.timestamp for e in self.evidence]
-        return {
-            "from": min(timestamps).isoformat(),
-            "to": max(timestamps).isoformat(),
-        }
-
-    @computed_field
-    @property
-    def evidence_count(self) -> int:
-        """Number of evidence items supporting this observation."""
-        return len(self.evidence)
-
-
-def compute_trend(
-    evidence: list[ObservationEvidence],
-    now: datetime | None = None,
-    recent_days: int = 30,
-    old_days: int = 90,
-) -> Trend:
-    """Compute the trend for an observation based on evidence timestamps.
-
-    The trend indicates how the evidence is distributed over time:
-    - STABLE: Evidence spread across time, continues to present
-    - STRENGTHENING: More evidence recently than historically
-    - WEAKENING: Evidence mostly old, sparse recently
-    - NEW: All evidence is recent (within recent_days)
-    - STALE: No evidence in recent window
-
-    Args:
-        evidence: List of evidence items with timestamps
-        now: Reference time for calculations (defaults to current UTC time)
-        recent_days: Number of days to consider "recent" (default 30)
-        old_days: Number of days to consider "old" (default 90)
-
-    Returns:
-        Computed Trend enum value
-    """
-    if now is None:
-        now = datetime.now(timezone.utc)
-
-    # Ensure now is timezone-aware
-    if now.tzinfo is None:
-        now = now.replace(tzinfo=timezone.utc)
-
-    if not evidence:
-        return Trend.STALE
-
-    recent_cutoff = now - timedelta(days=recent_days)
-    old_cutoff = now - timedelta(days=old_days)
-
-    # Normalize timestamps to UTC for comparison
-    def normalize_ts(ts: datetime) -> datetime:
-        if ts.tzinfo is None:
-            return ts.replace(tzinfo=timezone.utc)
-        return ts
-
-    recent = [e for e in evidence if normalize_ts(e.timestamp) > recent_cutoff]
-    old = [e for e in evidence if normalize_ts(e.timestamp) < old_cutoff]
-    middle = [e for e in evidence if old_cutoff <= normalize_ts(e.timestamp) <= recent_cutoff]
-
-    # No recent evidence = stale
-    if not recent:
-        return Trend.STALE
-
-    # All evidence is recent = new
-    if not old and not middle:
-        return Trend.NEW
-
-    # Compare density (evidence per day)
-    recent_density = len(recent) / recent_days if recent_days > 0 else 0
-    older_period = old_days - recent_days
-    older_density = (len(old) + len(middle)) / older_period if older_period > 0 else 0
-
-    # Avoid division by zero
-    if older_density == 0:
-        return Trend.NEW
-
-    ratio = recent_density / older_density
-
-    if ratio > 1.5:
-        return Trend.STRENGTHENING
-    elif ratio < 0.5:
-        return Trend.WEAKENING
-    else:
-        return Trend.STABLE
-
-
-class CandidateObservation(BaseModel):
-    """A candidate observation generated during the seed phase.
-
-    Candidates are preliminary observations that need evidence validation
-    before becoming full observations.
-    """
-
-    content: str = Field(description="The proposed observation content")
-    seed_memory_ids: list[str] = Field(default_factory=list, description="Memory IDs that inspired this candidate")
-
-
-class CandidateWithEvidence(BaseModel):
-    """A candidate observation with gathered supporting and contradicting evidence."""
-
-    candidate: CandidateObservation
-    supporting_memories: list[dict] = Field(default_factory=list, description="Memories that support this observation")
-    contradicting_memories: list[dict] = Field(
-        default_factory=list, description="Memories that contradict this observation"
-    )
-
-
-class MentalModelSnapshot(BaseModel):
-    """A versioned snapshot of a mental model's observations.
-
-    Used for tracking changes over time and enabling diff views.
-    """
-
-    version: int = Field(description="Version number (1-indexed)")
-    observations: list[Observation] = Field(default_factory=list, description="Observations at this version")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc), description="When this version was created"
-    )
-    reflect_summary: str | None = Field(default=None, description="Summary of changes in this version")
-
-
-def verify_evidence_quotes(
-    observation: Observation,
-    memories: dict[str, str],
-) -> tuple[bool, list[str]]:
-    """Verify that all evidence quotes exist in the referenced memories.
-
-    Args:
-        observation: The observation to verify
-        memories: Dict mapping memory_id to memory content
-
-    Returns:
-        Tuple of (is_valid, list of error messages)
-    """
-    errors = []
-
-    for evidence in observation.evidence:
-        memory_content = memories.get(evidence.memory_id)
-        if memory_content is None:
-            errors.append(f"Memory {evidence.memory_id} not found")
-            continue
-
-        if evidence.quote not in memory_content:
-            errors.append(f"Quote not found in memory {evidence.memory_id}: '{evidence.quote[:50]}...'")
-
-    return len(errors) == 0, errors
@@ -1,762 +0,0 @@
-"""
-System prompts for the reflect agent.
-"""
-
-import json
-from typing import Any
-
-
-def _extract_directive_rules(directives: list[dict[str, Any]]) -> list[str]:
-    """
-    Extract directive rules as a list of strings.
-
-    Args:
-        directives: List of directive mental models with observations
-
-    Returns:
-        List of directive rule strings
-    """
-    rules = []
-    for directive in directives:
-        directive_name = directive.get("name", "")
-        observations = directive.get("observations", [])
-        if observations:
-            for obs in observations:
-                # Support both Pydantic Observation objects and dicts
-                if hasattr(obs, "title"):
-                    title = obs.title
-                    content = obs.content
-                else:
-                    title = obs.get("title", "")
-                    content = obs.get("content", "")
-                if title and content:
-                    rules.append(f"**{title}**: {content}")
-                elif content:
-                    rules.append(content)
-        elif directive_name:
-            # Fallback to description if no observations
-            desc = directive.get("description", "")
-            if desc:
-                rules.append(f"**{directive_name}**: {desc}")
-    return rules
-
-
-def build_directives_section(directives: list[dict[str, Any]]) -> str:
-    """
-    Build the directives section for the system prompt.
-
-    Directives are hard rules that MUST be followed in all responses.
-
-    Args:
-        directives: List of directive mental models with observations
-    """
-    if not directives:
-        return ""
-
-    rules = _extract_directive_rules(directives)
-    if not rules:
-        return ""
-
-    parts = [
-        "## DIRECTIVES (MANDATORY)",
-        "These are hard rules you MUST follow in ALL responses:",
-        "",
-    ]
-
-    for rule in rules:
-        parts.append(f"- {rule}")
-
-    parts.extend(
-        [
-            "",
-            "NEVER violate these directives, even if other context suggests otherwise.",
-            "IMPORTANT: Do NOT explain or justify how you handled directives in your answer. Just follow them silently.",
-            "",
-        ]
-    )
-    return "\n".join(parts)
-
-
-def build_directives_reminder(directives: list[dict[str, Any]]) -> str:
-    """
-    Build a reminder section for directives to place at the end of the prompt.
-
-    Args:
-        directives: List of directive mental models with observations
-    """
-    if not directives:
-        return ""
-
-    rules = _extract_directive_rules(directives)
-    if not rules:
-        return ""
-
-    parts = [
-        "",
-        "## REMINDER: MANDATORY DIRECTIVES",
-        "Before responding, ensure your answer complies with ALL of these directives:",
-        "",
-    ]
-
-    for i, rule in enumerate(rules, 1):
-        parts.append(f"{i}. {rule}")
-
-    parts.append("")
-    parts.append("Your response will be REJECTED if it violates any directive above.")
-    parts.append("Do NOT include any commentary about how you handled directives - just follow them.")
-    return "\n".join(parts)
-
-
-def build_system_prompt_for_tools(
-    bank_profile: dict[str, Any],
-    context: str | None = None,
-    directives: list[dict[str, Any]] | None = None,
-) -> str:
-    """
-    Build the system prompt for tool-calling reflect agent.
-
-    This is a simplified prompt since tools are defined separately via the tools parameter.
-
-    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
-    """
-    name = bank_profile.get("name", "Assistant")
-    mission = bank_profile.get("mission", "")
-
-    no_info_rule = (
-        "- Only say 'I don't have information' AFTER trying list_mental_models AND recall with no relevant results"
-    )
-
-    parts = []
-
-    # Inject directives at the VERY START for maximum prominence
-    if directives:
-        parts.append(build_directives_section(directives))
-
-    parts.extend(
-        [
-            "You are a reflection agent that answers questions by reasoning over retrieved memories.",
-            "",
-        ]
-    )
-
-    parts.extend(
-        [
-            "## CRITICAL RULES",
-            "- You must NEVER fabricate information that has no basis in retrieved data",
-            "- You SHOULD synthesize, infer, and reason from the retrieved memories",
-            "- You MUST call recall() before saying you don't have information",
-            no_info_rule,
-            "",
-            "## How to Reason",
-            "- If memories mention someone did an activity, you can infer they likely enjoyed it",
-            "- Synthesize a coherent narrative from related memories",
-            "- Be a thoughtful interpreter, not just a literal repeater",
-            "- When the exact answer isn't stated, use what IS stated to give the best answer",
-            "",
-            "## Query Strategy (IMPORTANT)",
-            "recall() uses semantic search. NEVER just echo the user's question - decompose it into targeted searches:",
-            "",
-            "BAD: User asks 'recurring lesson themes between students' → recall('recurring lesson themes between students')",
-            "GOOD: Break it down into component searches:",
-            "  1. recall('lessons') - find all lesson-related memories",
-            "  2. recall('teaching sessions') - alternative phrasing",
-            "  3. recall('student progress') - find student-related memories",
-            "  4. recall('topics taught') - find subject matter",
-            "",
-            "Think: What ENTITIES and CONCEPTS does this question involve? Search for each separately.",
-            "- Questions about patterns → search for the individual instances first",
-            "- Questions comparing things → search for each thing separately",
-            "- Questions about relationships → search for each party involved",
-            "",
-            "## Workflow",
-        ]
-    )
-
-    # Answer mode: include mental model lookup in workflow
-    parts.extend(
-        [
-            "1. Review the pre-fetched mental models for relevant synthesized knowledge",
-            "2. If relevant, call get_mental_model(model_id) for full observations",
-            "3. DECOMPOSE the question into component searches (see Query Strategy above)",
-            "   - Identify entities and concepts in the question",
-            "   - Search for each separately with targeted queries",
-            "4. Run multiple recall() calls - don't just echo the user's question",
-            "5. Use expand() if you need more context on specific memories",
-            "6. BEFORE answering: Check if any person/project/concept from the memories deserves a mental model - use learn() if so",
-            "7. When ready, call done() with your answer and supporting memory_ids",
-            "",
-            "## When to Use learn() - IMPORTANT",
-            "ACTIVELY look for opportunities to use learn() when you discover:",
-            "- A person mentioned in 2+ memories who has no mental model yet",
-            "- A project or concept the user asks about that has no mental model",
-            "- A pattern or topic worth tracking for future questions",
-            "",
-            "DO NOT wait to be asked - proactively create models when you see the need.",
-            "Example: learn(name='Project Alpha', description='Track goals, status, and key decisions for Project Alpha')",
-            "",
-            "## 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 memory IDs ONLY in the memory_ids array parameter, not in the answer",
-        ]
-    )
-
-    parts.append("")
-    parts.append(f"## Memory Bank: {name}")
-
-    if mission:
-        parts.append(f"Mission: {mission}")
-
-    # Disposition traits
-    disposition = bank_profile.get("disposition", {})
-    if disposition:
-        traits = []
-        if "skepticism" in disposition:
-            traits.append(f"skepticism={disposition['skepticism']}")
-        if "literalism" in disposition:
-            traits.append(f"literalism={disposition['literalism']}")
-        if "empathy" in disposition:
-            traits.append(f"empathy={disposition['empathy']}")
-        if traits:
-            parts.append(f"Disposition: {', '.join(traits)}")
-
-    if context:
-        parts.append(f"\n## Additional Context\n{context}")
-
-    # Add directive reminder at the END for recency effect
-    if directives:
-        parts.append(build_directives_reminder(directives))
-
-    return "\n".join(parts)
-
-
-def build_agent_prompt(
-    query: str,
-    context_history: list[dict],
-    bank_profile: dict,
-    additional_context: str | None = None,
-) -> str:
-    """Build the user prompt for the reflect agent."""
-    parts = []
-
-    # Bank identity
-    name = bank_profile.get("name", "Assistant")
-    mission = bank_profile.get("mission", "")
-
-    parts.append(f"## Memory Bank Context\nName: {name}")
-    if mission:
-        parts.append(f"Mission: {mission}")
-
-    # Disposition traits if present
-    disposition = bank_profile.get("disposition", {})
-    if disposition:
-        traits = []
-        if "skepticism" in disposition:
-            traits.append(f"skepticism={disposition['skepticism']}")
-        if "literalism" in disposition:
-            traits.append(f"literalism={disposition['literalism']}")
-        if "empathy" in disposition:
-            traits.append(f"empathy={disposition['empathy']}")
-        if traits:
-            parts.append(f"Disposition: {', '.join(traits)}")
-
-    # Additional context from caller
-    if additional_context:
-        parts.append(f"\n## Additional Context\n{additional_context}")
-
-    # Tool call history
-    if context_history:
-        parts.append("\n## Tool Results (synthesize and reason from this data)")
-        for i, entry in enumerate(context_history, 1):
-            tool = entry["tool"]
-            output = entry["output"]
-            # Format as proper JSON for LLM readability
-            try:
-                output_str = json.dumps(output, indent=2, default=str)
-            except (TypeError, ValueError):
-                output_str = str(output)
-            parts.append(f"\n### Call {i}: {tool}\n```json\n{output_str}\n```")
-
-    # The question
-    parts.append(f"\n## Question\n{query}")
-
-    # Instructions
-    if context_history:
-        parts.append(
-            "\n## Instructions\n"
-            "Based on the tool results above, either call more tools or provide your final answer. "
-            "Synthesize and reason from the data - make reasonable inferences when helpful. "
-            "If you have related information, use it to give the best possible answer."
-        )
-    else:
-        parts.append(
-            "\n## Instructions\n"
-            "Start by calling list_mental_models() to see available mental models - they contain pre-synthesized knowledge. "
-            "If a relevant model exists, use get_mental_model(model_id) to get its observations. "
-            "Then use recall(query) for specific details not covered by mental models."
-        )
-
-    return "\n".join(parts)
-
-
-def build_final_prompt(
-    query: str,
-    context_history: list[dict],
-    bank_profile: dict,
-    additional_context: str | None = None,
-) -> str:
-    """Build the final prompt when forcing a text response (no tools)."""
-    parts = []
-
-    # Bank identity
-    name = bank_profile.get("name", "Assistant")
-    mission = bank_profile.get("mission", "")
-
-    parts.append(f"## Memory Bank Context\nName: {name}")
-    if mission:
-        parts.append(f"Mission: {mission}")
-
-    # Disposition traits if present
-    disposition = bank_profile.get("disposition", {})
-    if disposition:
-        traits = []
-        if "skepticism" in disposition:
-            traits.append(f"skepticism={disposition['skepticism']}")
-        if "literalism" in disposition:
-            traits.append(f"literalism={disposition['literalism']}")
-        if "empathy" in disposition:
-            traits.append(f"empathy={disposition['empathy']}")
-        if traits:
-            parts.append(f"Disposition: {', '.join(traits)}")
-
-    # Additional context from caller
-    if additional_context:
-        parts.append(f"\n## Additional Context\n{additional_context}")
-
-    # Tool call history
-    if context_history:
-        parts.append("\n## Retrieved Data (synthesize and reason from this data)")
-        for entry in context_history:
-            tool = entry["tool"]
-            output = entry["output"]
-            # Format as proper JSON for LLM readability
-            try:
-                output_str = json.dumps(output, indent=2, default=str)
-            except (TypeError, ValueError):
-                output_str = str(output)
-            parts.append(f"\n### From {tool}:\n```json\n{output_str}\n```")
-    else:
-        parts.append("\n## Retrieved Data\nNo data was retrieved.")
-
-    # The question
-    parts.append(f"\n## Question\n{query}")
-
-    # Final instructions
-    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."
-        "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."
-    )
-
-    return "\n".join(parts)
-
-
-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 say "I don't have information" if the retrieved data is truly unrelated to the question.
-Do NOT fabricate information that has no basis in the retrieved data."""
-
-
-# =============================================================================
-# 4-Phase Mental Model Reflect Prompts
-# =============================================================================
-
-SEED_PHASE_SYSTEM_PROMPT = """You are analyzing memories to discover NEW patterns and generate candidate observations.
-
-Your task is to identify potential observations (beliefs, preferences, patterns, behaviors) that could be part of a mental model about this person/topic.
-
-## Important: Avoid Redundancy
-If existing observations are provided, DO NOT generate candidates that are essentially the same.
-Focus on discovering NEW patterns not already covered by existing observations.
-
-## Rules
- Generate 5-15 candidate observations for NEW patterns only
- Each candidate should be specific and testable (can be supported or contradicted by evidence)
- Note which memory IDs inspired each candidate (these are seeds, not final evidence)
- Focus on patterns that appear MULTIPLE TIMES across many memories - the more the better
- The best candidates are ones you can find 10, 20, or even 50+ supporting memories for
- Skip patterns that are already covered by existing observations
-
-## Output Format
-Return a JSON array of candidate observations:
-```json
-{
-  "candidates": [
-    {
-      "content": "The specific observation/belief/pattern - be detailed and specific",
-      "seed_memory_ids": ["memory_id_1", "memory_id_2", "memory_id_3"]
-    }
-  ]
-}
-```
-
-Focus on patterns that appear multiple times or have strong signals. Don't generate obvious or trivial observations.
-Prefer candidates with MORE seed memories - they're more likely to be real patterns.
-Return an empty candidates array if no genuinely new patterns are found."""
-
-
-def build_seed_phase_prompt(
-    memories: list[dict],
-    topic: str | None = None,
-    existing_observations: list[dict] | None = None,
-) -> str:
-    """Build the user prompt for the seed phase.
-
-    Args:
-        memories: List of memories to analyze
-        topic: Optional topic focus for the mental model
-        existing_observations: Optional list of existing observations to avoid rediscovering
-    """
-    parts = []
-
-    if topic:
-        parts.append(f"## Topic Focus\n{topic}\n")
-
-    # Include existing observations so we don't rediscover them
-    if existing_observations:
-        parts.append("## Existing Observations (DO NOT regenerate these)")
-        parts.append("These patterns are already tracked. Focus on discovering NEW patterns:\n")
-        for i, obs in enumerate(existing_observations, 1):
-            title = obs.get("title", "")
-            content = obs.get("content", "")
-            parts.append(f"{i}. **{title}**: {content}\n")
-        parts.append("")
-
-    parts.append("## Memories to Analyze")
-    parts.append("Review these memories and identify patterns, preferences, beliefs, and behaviors:\n")
-
-    for mem in memories:
-        mem_id = mem.get("id", "unknown")
-        content = mem.get("content", mem.get("text", ""))
-        timestamp = mem.get("timestamp", mem.get("created_at", ""))
-        parts.append(f"[{mem_id}] ({timestamp}): {content}\n")
-
-    parts.append("\n## Instructions")
-    if existing_observations:
-        parts.append("Generate candidate observations for NEW patterns not already covered above.")
-        parts.append("If all patterns are already covered by existing observations, return an empty candidates array.")
-    else:
-        parts.append("Generate candidate observations based on patterns you see in these memories.")
-    parts.append("Look for: recurring themes, stated preferences, behavioral patterns, beliefs, values, goals.")
-
-    return "\n".join(parts)
-
-
-VALIDATE_PHASE_SYSTEM_PROMPT = """You are validating candidate observations against evidence.
-
-For each candidate, you have:
- Supporting memories (evidence FOR the observation)
- Contradicting memories (evidence AGAINST the observation)
-
-## Your Task
-1. Evaluate each candidate based on the evidence
-2. For valid candidates, extract EXACT QUOTES from supporting memories
-3. Discard candidates with insufficient or contradicting evidence
-4. Merge similar candidates into single, refined observations
-
-## Rules for Quotes
- Quotes must be EXACT text from the memory, not paraphrased
- Each quote should directly support the observation
- The MORE evidence quotes, the BETTER - don't limit yourself, include ALL relevant quotes (10, 20, 50+)
- Observations with only 1-2 quotes are weak and should be discarded unless the evidence is exceptionally strong
- Stronger observations have more supporting evidence - aim for comprehensive coverage
-
-## Output Format
-Return validated observations with evidence:
-```json
-{
-  "observations": [
-    {
-      "title": "Short descriptive title (3-8 words) - like a headline",
-      "content": "The full observation content - detailed explanation of the pattern/belief",
-      "evidence": [
-        {
-          "memory_id": "exact_memory_id",
-          "quote": "Exact quote from the memory text",
-          "relevance": "Brief explanation of how this supports the observation",
-          "timestamp": "2024-01-15T10:00:00Z"
-        }
-      ]
-    }
-  ],
-  "discarded": [
-    {
-      "content": "The discarded candidate",
-      "reason": "Why it was discarded (insufficient evidence, contradicted, etc.)"
-    }
-  ],
-  "merged": [
-    {
-      "from": ["candidate 1 content", "candidate 2 content"],
-      "into": "The merged observation content"
-    }
-  ]
-}
-```
-
-## Title Guidelines
- Title should be a SHORT label (like "Prefers morning meetings" or "Coffee enthusiast")
- NOT a truncated version of the content
- Think of it as a category/tag for the observation
-
-Be rigorous: only keep observations with clear, verifiable evidence from multiple memories."""
-
-
-def build_validate_phase_prompt(candidates_with_evidence: list[dict]) -> str:
-    """Build the user prompt for the validate phase."""
-    parts = ["## Candidates to Validate\n"]
-
-    for i, item in enumerate(candidates_with_evidence, 1):
-        candidate = item.get("candidate", {})
-        supporting = item.get("supporting_memories", [])
-        contradicting = item.get("contradicting_memories", [])
-
-        parts.append(f"### Candidate {i}: {candidate.get('content', '')}")
-
-        if supporting:
-            parts.append("\n**Supporting Evidence:**")
-            for mem in supporting:
-                mem_id = mem.get("id", "unknown")
-                content = mem.get("content", mem.get("text", ""))
-                timestamp = mem.get("timestamp", mem.get("created_at", ""))
-                parts.append(f"- [{mem_id}] ({timestamp}): {content}")
-
-        if contradicting:
-            parts.append("\n**Contradicting Evidence:**")
-            for mem in contradicting:
-                mem_id = mem.get("id", "unknown")
-                content = mem.get("content", mem.get("text", ""))
-                timestamp = mem.get("timestamp", mem.get("created_at", ""))
-                parts.append(f"- [{mem_id}] ({timestamp}): {content}")
-
-        if not supporting and not contradicting:
-            parts.append("\n*No additional evidence found*")
-
-        parts.append("")
-
-    parts.append("## Instructions")
-    parts.append("1. Evaluate each candidate based on its evidence")
-    parts.append("2. Keep candidates with strong supporting evidence")
-    parts.append("3. Discard candidates with no evidence or strong contradictions")
-    parts.append("4. Merge similar candidates")
-    parts.append("5. Extract EXACT quotes (copy-paste from memory text) for evidence")
-
-    return "\n".join(parts)
-
-
-COMPARE_PHASE_SYSTEM_PROMPT = """You are merging new observations with an existing mental model.
-
-You have:
- EXISTING observations (from the current mental model)
- NEW observations (from this reflect cycle)
-
-## Your Task
-Produce the final, complete mental model by:
-1. Keeping existing observations that are still valid
-2. Updating existing observations with new evidence (ADD new evidence to existing)
-3. Adding new observations that don't overlap with existing
-4. Removing existing observations that are contradicted by new evidence
-5. Merging overlapping observations
-
-## Rules
- The final model should have no contradictions
- Each observation must have evidence with exact quotes
- COMBINE evidence from both existing and new observations
- If an existing observation has new supporting evidence, ADD ALL the new evidence to it
- Include ALL relevant evidence - the more quotes the better (10, 20, 50+ is great)
- Observations with more evidence are more reliable - don't limit the number of quotes
-
-## Output Format
-Return the complete, final mental model:
-```json
-{
-  "observations": [
-    {
-      "title": "Short descriptive title (3-8 words)",
-      "content": "Full observation content - detailed explanation",
-      "evidence": [
-        {
-          "memory_id": "id",
-          "quote": "exact quote",
-          "relevance": "explanation",
-          "timestamp": "ISO timestamp"
-        }
-      ],
-      "created_at": "ISO timestamp of when observation was first created"
-    }
-  ],
-  "changes": {
-    "kept": ["Observation that was kept unchanged"],
-    "updated": [{"from": "old content", "to": "new content", "reason": "why"}],
-    "added": ["New observation that was added"],
-    "removed": [{"content": "removed observation", "reason": "why removed"}],
-    "merged": [{"from": ["obs1", "obs2"], "into": "merged observation"}]
-  }
-}
-```"""
-
-
-def build_compare_phase_prompt(
-    existing_observations: list[dict],
-    new_observations: list[dict],
-) -> str:
-    """Build the user prompt for the compare phase."""
-    parts = []
-
-    parts.append("## Existing Mental Model Observations")
-    if existing_observations:
-        for i, obs in enumerate(existing_observations, 1):
-            title = obs.get("title", "")
-            content = obs.get("content", obs.get("text", ""))
-            evidence = obs.get("evidence", [])
-            parts.append(f"\n### Existing {i}: {title}")
-            parts.append(f"Content: {content}")
-            if evidence:
-                parts.append(f"Evidence ({len(evidence)} items):")
-                for ev in evidence[:5]:  # Show max 5 evidence items
-                    parts.append(f'  - [{ev.get("memory_id", "?")}]: "{ev.get("quote", "")}"')
-                if len(evidence) > 5:
-                    parts.append(f"  ... and {len(evidence) - 5} more")
-    else:
-        parts.append("*No existing observations*")
-
-    parts.append("\n## New Observations from This Reflect")
-    if new_observations:
-        for i, obs in enumerate(new_observations, 1):
-            title = obs.get("title", "")
-            content = obs.get("content", "")
-            evidence = obs.get("evidence", [])
-            parts.append(f"\n### New {i}: {title}")
-            parts.append(f"Content: {content}")
-            if evidence:
-                parts.append(f"Evidence ({len(evidence)} items):")
-                for ev in evidence:
-                    parts.append(f'  - [{ev.get("memory_id", "?")}]: "{ev.get("quote", "")}"')
-    else:
-        parts.append("*No new observations*")
-
-    parts.append("\n## Instructions")
-    parts.append("Merge these into a coherent, non-contradictory mental model.")
-    parts.append("Preserve all valid evidence. Remove stale or contradicted observations.")
-
-    return "\n".join(parts)
-
-
-# =============================================================================
-# UPDATE EXISTING Phase Prompts (for diff-based refresh)
-# =============================================================================
-
-UPDATE_EXISTING_SYSTEM_PROMPT = """You are updating existing observations with newly found evidence.
-
-For each existing observation, you have been given:
- The original observation (title, content, existing evidence)
- Newly found supporting memories
- Newly found contradicting memories
-
-## Your Task
-1. Extract EXACT QUOTES from new supporting memories to add to the observation
-2. Flag observations with strong contradicting evidence for potential removal
-3. Keep existing evidence intact - only ADD new evidence
-
-## Rules for Quotes
- Quotes must be EXACT text from the memory, not paraphrased
- Each quote should directly support the observation
- Include ALL relevant quotes from the new memories
-
-## Output Format
-Return updated observations with new evidence:
-```json
-{
-  "updated_observations": [
-    {
-      "title": "Original title",
-      "content": "Original content",
-      "existing_evidence_count": 5,
-      "new_evidence": [
-        {
-          "memory_id": "exact_memory_id",
-          "quote": "Exact quote from the memory text",
-          "relevance": "Brief explanation of how this supports the observation",
-          "timestamp": "2024-01-15T10:00:00Z"
-        }
-      ],
-      "has_contradiction": false,
-      "contradiction_note": null
-    }
-  ]
-}
-```
-
-If an observation has strong contradicting evidence, set has_contradiction=true and explain in contradiction_note."""
-
-
-def build_update_existing_prompt(observations_with_evidence: list[dict]) -> str:
-    """Build the user prompt for the update existing phase.
-
-    Args:
-        observations_with_evidence: List of existing observations with new evidence found
-    """
-    parts = ["## Existing Observations to Update\n"]
-
-    for i, item in enumerate(observations_with_evidence, 1):
-        obs = item.get("observation", {})
-        supporting = item.get("supporting_memories", [])
-        contradicting = item.get("contradicting_memories", [])
-
-        title = obs.get("title", "")
-        content = obs.get("content", "")
-        existing_evidence = obs.get("evidence", [])
-
-        parts.append(f"### Observation {i}: {title}")
-        parts.append(f"Content: {content}")
-        parts.append(f"Existing evidence count: {len(existing_evidence)}")
-
-        if supporting:
-            parts.append("\n**New Supporting Memories:**")
-            for mem in supporting:
-                mem_id = mem.get("id", "unknown")
-                mem_content = mem.get("content", mem.get("text", ""))
-                timestamp = mem.get("timestamp", mem.get("created_at", ""))
-                parts.append(f"- [{mem_id}] ({timestamp}): {mem_content}")
-
-        if contradicting:
-            parts.append("\n**New Contradicting Memories:**")
-            for mem in contradicting:
-                mem_id = mem.get("id", "unknown")
-                mem_content = mem.get("content", mem.get("text", ""))
-                timestamp = mem.get("timestamp", mem.get("created_at", ""))
-                parts.append(f"- [{mem_id}] ({timestamp}): {mem_content}")
-
-        if not supporting and not contradicting:
-            parts.append("\n*No new evidence found*")
-
-        parts.append("")
-
-    parts.append("## Instructions")
-    parts.append("1. Extract EXACT quotes from new supporting memories")
-    parts.append("2. Flag observations with strong contradictions")
-    parts.append("3. Return the updated observations with new evidence added")
-
-    return "\n".join(parts)
@@ -1,450 +0,0 @@
-"""
-Tool implementations for the reflect agent.
-"""
-
-import logging
-import re
-import uuid
-from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any
-
-from .models import MentalModelInput
-from .observations import Observation, ObservationEvidence, Trend
-
-if TYPE_CHECKING:
-    from asyncpg import Connection
-
-    from ...api.http import RequestContext
-    from ..memory_engine import MemoryEngine
-
-logger = logging.getLogger(__name__)
-
-
-def generate_model_id(name: str) -> str:
-    """Generate a stable ID from mental model name."""
-    # Normalize: lowercase, replace spaces/special chars with hyphens
-    normalized = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
-    # Truncate to reasonable length
-    return normalized[:50]
-
-
-def _parse_observations(observations_raw: list) -> list[Observation]:
-    """Parse raw observation dicts into typed Observation models."""
-    observations: list[Observation] = []
-    for obs in observations_raw:
-        if not isinstance(obs, dict):
-            continue
-
-        try:
-            parsed = Observation(
-                title=obs.get("title", ""),
-                content=obs.get("content", ""),
-                evidence=[
-                    ObservationEvidence(
-                        memory_id=ev.get("memory_id", ""),
-                        quote=ev.get("quote", ""),
-                        relevance=ev.get("relevance", ""),
-                        timestamp=ev.get("timestamp"),
-                    )
-                    for ev in obs.get("evidence", [])
-                    if isinstance(ev, dict)
-                ],
-                created_at=obs.get("created_at"),
-            )
-            observations.append(parsed)
-        except Exception as e:
-            logger.warning(f"Failed to parse observation: {e}")
-            continue
-
-    return observations
-
-
-async def tool_lookup(
-    conn: "Connection",
-    bank_id: str,
-    model_id: str | None = None,
-    tags: list[str] | None = None,
-    tags_match: str = "any",
-) -> dict[str, Any]:
-    """
-    List or get mental models.
-
-    Args:
-        conn: Database connection
-        bank_id: Bank identifier
-        model_id: Optional specific model ID to get (if None, lists all)
-        tags: Optional tags to filter models (when listing)
-        tags_match: How to match tags - "any" (OR), "all" (AND)
-
-    Returns:
-        Dict with either a list of models or a single model's details
-    """
-    if model_id:
-        # Get specific mental model with full details including observations
-        row = await conn.fetchrow(
-            """
-            SELECT id, subtype, name, description, observations, entity_id, last_updated
-            FROM mental_models
-            WHERE id = $1 AND bank_id = $2
-            """,
-            model_id,
-            bank_id,
-        )
-        if row:
-            # Parse observations JSON
-            obs_data = row["observations"] or {"observations": []}
-            if isinstance(obs_data, str):
-                import json
-
-                obs_data = json.loads(obs_data)
-            observations_raw = obs_data.get("observations", []) if isinstance(obs_data, dict) else obs_data
-
-            # Parse observations into typed models
-            observations = _parse_observations(observations_raw)
-
-            return {
-                "found": True,
-                "model": {
-                    "id": row["id"],
-                    "subtype": row["subtype"],
-                    "name": row["name"],
-                    "description": row["description"],
-                    "observations": observations,
-                    "entity_id": str(row["entity_id"]) if row["entity_id"] else None,
-                    "last_updated": row["last_updated"].isoformat() if row["last_updated"] else None,
-                },
-            }
-        return {"found": False, "model_id": model_id}
-    else:
-        # List mental models (compact: id, name, description only)
-        # Full observations are retrieved via get_mental_model(model_id)
-        # NOTE: Directives (subtype='directive') are excluded from listing -
-        # they are injected into the system prompt, not discoverable via tools
-        # Filter by tags if provided
-        if tags:
-            if tags_match == "all":
-                # All tags must match
-                rows = await conn.fetch(
-                    """
-                    SELECT id, subtype, name, description
-                    FROM mental_models
-                    WHERE bank_id = $1 AND tags @> $2::varchar[] AND subtype != 'directive'
-                    ORDER BY last_updated DESC NULLS LAST, created_at DESC
-                    """,
-                    bank_id,
-                    tags,
-                )
-            else:
-                # Any tag matches (OR) - default
-                rows = await conn.fetch(
-                    """
-                    SELECT id, subtype, name, description
-                    FROM mental_models
-                    WHERE bank_id = $1 AND tags && $2::varchar[] AND subtype != 'directive'
-                    ORDER BY last_updated DESC NULLS LAST, created_at DESC
-                    """,
-                    bank_id,
-                    tags,
-                )
-        else:
-            rows = await conn.fetch(
-                """
-                SELECT id, subtype, name, description
-                FROM mental_models
-                WHERE bank_id = $1 AND subtype != 'directive'
-                ORDER BY last_updated DESC NULLS LAST, created_at DESC
-                """,
-                bank_id,
-            )
-
-        return {
-            "count": len(rows),
-            "models": [
-                {
-                    "id": row["id"],
-                    "subtype": row["subtype"],
-                    "name": row["name"],
-                    "description": row["description"],
-                }
-                for row in rows
-            ],
-        }
-
-
-async def tool_recall(
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    query: str,
-    request_context: "RequestContext",
-    max_tokens: int = 2048,
-    max_results: int = 50,
-    tags: list[str] | None = None,
-    tags_match: str = "any",
-    connection_budget: int = 1,
-) -> dict[str, Any]:
-    """
-    Search memories using TEMPR retrieval.
-
-    Args:
-        memory_engine: Memory engine instance
-        bank_id: Bank identifier
-        query: Search query
-        request_context: Request context for authentication
-        max_tokens: Maximum tokens for results (default 2048)
-        max_results: Maximum number of results
-        tags: Filter by tags (includes untagged memories)
-        tags_match: How to match tags - "any" (OR), "all" (AND), or "exact"
-        connection_budget: Max DB connections for this recall (default 1 for internal ops)
-
-    Returns:
-        Dict with list of matching memories
-    """
-    result = await memory_engine.recall_async(
-        bank_id=bank_id,
-        query=query,
-        fact_type=["experience", "world"],  # Exclude opinions
-        max_tokens=max_tokens,
-        enable_trace=False,
-        request_context=request_context,
-        tags=tags,
-        tags_match=tags_match,
-        _connection_budget=connection_budget,
-    )
-
-    memories = []
-    for m in result.results[:max_results]:
-        memories.append(
-            {
-                "id": str(m.id),
-                "text": m.text,
-                "type": m.fact_type,
-                "entities": m.entities or [],
-                "occurred": m.occurred_start,  # Already ISO format string
-            }
-        )
-
-    return {
-        "query": query,
-        "count": len(memories),
-        "memories": memories,
-    }
-
-
-async def tool_learn(
-    conn: "Connection",
-    bank_id: str,
-    input: MentalModelInput,
-    tags: list[str] | None = None,
-) -> dict[str, Any]:
-    """
-    Create a mental model placeholder with subtype='learned'.
-
-    The agent only specifies name and description - actual observations are generated
-    in the background via refresh, similar to pinned models.
-
-    Args:
-        conn: Database connection
-        bank_id: Bank identifier
-        input: Mental model input data (name, description, optional entity_id)
-        tags: Tags to apply to new mental models (from reflect context)
-
-    Returns:
-        Dict with created model info including model_id for background generation
-    """
-    model_id = generate_model_id(input.name)
-
-    # Parse entity_id if provided
-    entity_uuid = None
-    if input.entity_id:
-        try:
-            entity_uuid = uuid.UUID(input.entity_id)
-        except ValueError:
-            logger.warning(f"Invalid entity_id format: {input.entity_id}")
-
-    # Check if model exists
-    existing = await conn.fetchrow(
-        "SELECT id FROM mental_models WHERE id = $1 AND bank_id = $2",
-        model_id,
-        bank_id,
-    )
-
-    if existing:
-        # Update description only - observations will be regenerated
-        await conn.execute(
-            """
-            UPDATE mental_models SET
-                description = $3,
-                entity_id = $4
-            WHERE id = $1 AND bank_id = $2
-            """,
-            model_id,
-            bank_id,
-            input.description,
-            entity_uuid,
-        )
-        status = "updated"
-    else:
-        # Insert new model placeholder - observations will be generated in background
-        await conn.execute(
-            """
-            INSERT INTO mental_models (id, bank_id, subtype, name, description, observations, entity_id, tags, created_at)
-            VALUES ($1, $2, 'learned', $3, $4, '{}'::jsonb, $5, $6, NOW())
-            """,
-            model_id,
-            bank_id,
-            input.name,
-            input.description,
-            entity_uuid,
-            tags or [],
-        )
-        status = "created"
-
-    logger.info(f"[REFLECT] Mental model '{model_id}' {status} in bank {bank_id} - pending background generation")
-
-    return {
-        "status": status,
-        "model_id": model_id,
-        "name": input.name,
-        "pending_generation": True,
-    }
-
-
-async def tool_expand(
-    conn: "Connection",
-    bank_id: str,
-    memory_ids: list[str],
-    depth: str,
-) -> dict[str, Any]:
-    """
-    Expand multiple memories to get chunk or document context.
-
-    Args:
-        conn: Database connection
-        bank_id: Bank identifier
-        memory_ids: List of memory unit IDs
-        depth: "chunk" or "document"
-
-    Returns:
-        Dict with results array, each containing memory, chunk, and optionally document data
-    """
-    if not memory_ids:
-        return {"error": "memory_ids is required and must not be empty"}
-
-    # Validate and convert UUIDs
-    valid_uuids: list[uuid.UUID] = []
-    errors: dict[str, str] = {}
-    for mid in memory_ids:
-        try:
-            valid_uuids.append(uuid.UUID(mid))
-        except ValueError:
-            errors[mid] = f"Invalid memory_id format: {mid}"
-
-    if not valid_uuids:
-        return {"error": "No valid memory IDs provided", "details": errors}
-
-    # Batch fetch all memory units
-    memories = await conn.fetch(
-        """
-        SELECT id, text, chunk_id, document_id, fact_type, context
-        FROM memory_units
-        WHERE id = ANY($1) AND bank_id = $2
-        """,
-        valid_uuids,
-        bank_id,
-    )
-    memory_map = {row["id"]: row for row in memories}
-
-    # Collect chunk_ids and document_ids for batch fetching
-    chunk_ids = [m["chunk_id"] for m in memories if m["chunk_id"]]
-    doc_ids_from_chunks: set[str] = set()
-    doc_ids_direct: set[str] = set()
-
-    # Batch fetch all chunks
-    chunk_map: dict[str, Any] = {}
-    if chunk_ids:
-        chunks = await conn.fetch(
-            """
-            SELECT chunk_id, chunk_text, chunk_index, document_id
-            FROM chunks
-            WHERE chunk_id = ANY($1)
-            """,
-            chunk_ids,
-        )
-        chunk_map = {row["chunk_id"]: row for row in chunks}
-        if depth == "document":
-            doc_ids_from_chunks = {c["document_id"] for c in chunks if c["document_id"]}
-
-    # Collect direct document IDs (memories without chunks)
-    if depth == "document":
-        for m in memories:
-            if not m["chunk_id"] and m["document_id"]:
-                doc_ids_direct.add(m["document_id"])
-
-    # Batch fetch all documents
-    doc_map: dict[str, Any] = {}
-    all_doc_ids = list(doc_ids_from_chunks | doc_ids_direct)
-    if all_doc_ids:
-        docs = await conn.fetch(
-            """
-            SELECT id, original_text, metadata, retain_params
-            FROM documents
-            WHERE id = ANY($1) AND bank_id = $2
-            """,
-            all_doc_ids,
-            bank_id,
-        )
-        doc_map = {row["id"]: row for row in docs}
-
-    # Build results
-    results: list[dict[str, Any]] = []
-    for mid, mem_uuid in zip(memory_ids, valid_uuids):
-        if mid in errors:
-            results.append({"memory_id": mid, "error": errors[mid]})
-            continue
-
-        memory = memory_map.get(mem_uuid)
-        if not memory:
-            results.append({"memory_id": mid, "error": f"Memory not found: {mid}"})
-            continue
-
-        item: dict[str, Any] = {
-            "memory_id": mid,
-            "memory": {
-                "id": str(memory["id"]),
-                "text": memory["text"],
-                "type": memory["fact_type"],
-                "context": memory["context"],
-            },
-        }
-
-        # Add chunk if available
-        if memory["chunk_id"] and memory["chunk_id"] in chunk_map:
-            chunk = chunk_map[memory["chunk_id"]]
-            item["chunk"] = {
-                "id": chunk["chunk_id"],
-                "text": chunk["chunk_text"],
-                "index": chunk["chunk_index"],
-                "document_id": chunk["document_id"],
-            }
-            # Add document if depth=document
-            if depth == "document" and chunk["document_id"] in doc_map:
-                doc = doc_map[chunk["document_id"]]
-                item["document"] = {
-                    "id": doc["id"],
-                    "full_text": doc["original_text"],
-                    "metadata": doc["metadata"],
-                    "retain_params": doc["retain_params"],
-                }
-        elif memory["document_id"] and depth == "document" and memory["document_id"] in doc_map:
-            # No chunk, but has document_id
-            doc = doc_map[memory["document_id"]]
-            item["document"] = {
-                "id": doc["id"],
-                "full_text": doc["original_text"],
-                "metadata": doc["metadata"],
-                "retain_params": doc["retain_params"],
-            }
-
-        results.append(item)
-
-    return {"results": results, "count": len(results)}
@@ -1,218 +0,0 @@
-"""
-Tool schema definitions for the reflect agent.
-
-These are OpenAI-format tool definitions used with native tool calling.
-"""
-
-# Tool definitions in OpenAI format
-TOOL_LIST_MENTAL_MODELS = {
-    "type": "function",
-    "function": {
-        "name": "list_mental_models",
-        "description": "List all available mental models - your synthesized knowledge about entities, concepts, and events. Returns an array of models with id, name, and description.",
-        "parameters": {
-            "type": "object",
-            "properties": {},
-            "required": [],
-        },
-    },
-}
-
-TOOL_GET_MENTAL_MODEL = {
-    "type": "function",
-    "function": {
-        "name": "get_mental_model",
-        "description": "Get full details of a specific mental model including all observations and memory references.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "model_id": {
-                    "type": "string",
-                    "description": "ID of the mental model (from list_mental_models results)",
-                },
-            },
-            "required": ["model_id"],
-        },
-    },
-}
-
-TOOL_RECALL = {
-    "type": "function",
-    "function": {
-        "name": "recall",
-        "description": "Search memories using semantic + temporal retrieval. Returns relevant memories from experience and world knowledge, each with an 'id' you can reference.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "Search query string",
-                },
-                "max_tokens": {
-                    "type": "integer",
-                    "description": "Optional limit on result size (default 2048). Use higher values for broader searches.",
-                },
-            },
-            "required": ["query"],
-        },
-    },
-}
-
-TOOL_LEARN = {
-    "type": "function",
-    "function": {
-        "name": "learn",
-        "description": "Create a new mental model to track an important recurring topic. Use when you discover a person, project, concept, or pattern that appears frequently and would benefit from synthesized knowledge. The model content will be generated automatically.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "name": {
-                    "type": "string",
-                    "description": "Human-readable name (e.g., 'Project Alpha', 'John Smith', 'Product Strategy')",
-                },
-                "description": {
-                    "type": "string",
-                    "description": "What to track and synthesize (e.g., 'Track goals, milestones, blockers, and key decisions for Project Alpha')",
-                },
-            },
-            "required": ["name", "description"],
-        },
-    },
-}
-
-TOOL_EXPAND = {
-    "type": "function",
-    "function": {
-        "name": "expand",
-        "description": "Get more context for one or more memories. Memory hierarchy: memory -> chunk -> document.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "memory_ids": {
-                    "type": "array",
-                    "items": {"type": "string"},
-                    "description": "Array of memory IDs from recall results (batch multiple for efficiency)",
-                },
-                "depth": {
-                    "type": "string",
-                    "enum": ["chunk", "document"],
-                    "description": "chunk: surrounding text chunk, document: full source document",
-                },
-            },
-            "required": ["memory_ids", "depth"],
-        },
-    },
-}
-
-TOOL_DONE_ANSWER = {
-    "type": "function",
-    "function": {
-        "name": "done",
-        "description": "Signal completion with your final answer. Use this when you have gathered enough information to answer the question.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "answer": {
-                    "type": "string",
-                    "description": "Your response as plain text. Do NOT use markdown formatting. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
-                },
-                "memory_ids": {
-                    "type": "array",
-                    "items": {"type": "string"},
-                    "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
-                },
-                "model_ids": {
-                    "type": "array",
-                    "items": {"type": "string"},
-                    "description": "Array of mental model IDs that support your answer",
-                },
-            },
-            "required": ["answer"],
-        },
-    },
-}
-
-
-def _build_done_tool_with_directives(directive_rules: list[str]) -> dict:
-    """
-    Build the done tool schema with directive compliance field.
-
-    When directives are present, adds a required field that forces the agent
-    to confirm compliance with each directive before submitting.
-
-    Args:
-        directive_rules: List of directive rule strings
-    """
-    from typing import Any, cast
-
-    # Build rules list for description
-    rules_list = "\n".join(f"  {i + 1}. {rule}" for i, rule in enumerate(directive_rules))
-
-    # Build the tool with directive compliance field
-    return {
-        "type": "function",
-        "function": {
-            "name": "done",
-            "description": (
-                "Signal completion with your final answer. IMPORTANT: You must confirm directive compliance before submitting. "
-                "Your answer will be REJECTED if it violates any directive."
-            ),
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "answer": {
-                        "type": "string",
-                        "description": "Your response as plain text. Do NOT use markdown formatting. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
-                    },
-                    "memory_ids": {
-                        "type": "array",
-                        "items": {"type": "string"},
-                        "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
-                    },
-                    "model_ids": {
-                        "type": "array",
-                        "items": {"type": "string"},
-                        "description": "Array of mental model 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]...'",
-                    },
-                },
-                "required": ["answer", "directive_compliance"],
-            },
-        },
-    }
-
-
-def get_reflect_tools(enable_learn: bool = True, directive_rules: list[str] | None = None) -> list[dict]:
-    """
-    Get the list of tools for the reflect agent.
-
-    Args:
-        enable_learn: Whether to include the learn tool
-        directive_rules: Optional list of directive rule strings. If provided,
-                        the done() tool will require directive compliance confirmation.
-
-    Returns:
-        List of tool definitions in OpenAI format
-    """
-    tools = []
-
-    # Include mental model tools for lookup
-    tools.append(TOOL_LIST_MENTAL_MODELS)
-    tools.append(TOOL_GET_MENTAL_MODEL)
-    tools.append(TOOL_RECALL)
-
-    if enable_learn:
-        tools.append(TOOL_LEARN)
-
-    tools.append(TOOL_EXPAND)
-
-    # Use directive-aware done tool if directives are present
-    if directive_rules:
-        tools.append(_build_done_tool_with_directives(directive_rules))
-    else:
-        tools.append(TOOL_DONE_ANSWER)
-
-    return tools
@@ -10,91 +10,8 @@ from typing import Any

 from pydantic import BaseModel, ConfigDict, Field

-# Valid fact types for recall operations (excludes 'observation' which is internal, and 'opinion' which is deprecated)
-VALID_RECALL_FACT_TYPES = frozenset(["world", "experience"])
-
-
-class LLMToolCall(BaseModel):
-    """A tool call requested by the LLM."""
-
-    id: str = Field(description="Unique identifier for this tool call")
-    name: str = Field(description="Name of the tool to call")
-    arguments: dict[str, Any] = Field(description="Arguments to pass to the tool")
-
-
-class LLMToolCallResult(BaseModel):
-    """Result from an LLM call that may include tool calls."""
-
-    content: str | None = Field(default=None, description="Text content if any")
-    tool_calls: list[LLMToolCall] = Field(default_factory=list, description="Tool calls requested by the LLM")
-    finish_reason: str | None = Field(default=None, description="Reason the LLM stopped: 'stop', 'tool_calls', etc.")
-
-
-class ToolCallTrace(BaseModel):
-    """A single tool call made during reflect."""
-
-    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")
-    iteration: int = Field(default=0, description="Iteration number (1-based) when this tool was called")
-
-
-class LLMCallTrace(BaseModel):
-    """A single LLM call made during reflect."""
-
-    scope: str = Field(description="Call scope: agent_1, agent_2, final, etc.")
-    duration_ms: int = Field(description="Execution time in milliseconds")
-
-
-class MentalModelRef(BaseModel):
-    """Reference to a mental model accessed during reflect."""
-
-    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)")
-
-
-class DirectiveRef(BaseModel):
-    """Reference to a directive that was applied during reflect."""
-
-    id: str = Field(description="Directive mental model ID")
-    name: str = Field(description="Directive name")
-    rules: list[str] = Field(default_factory=list, description="Directive rules/observations that were applied")
-
-
-class TokenUsage(BaseModel):
-    """
-    Token usage metrics for LLM calls.
-
-    Tracks input/output tokens for a single request to enable
-    per-request cost tracking and monitoring.
-    """
-
-    model_config = ConfigDict(
-        json_schema_extra={
-            "example": {
-                "input_tokens": 1500,
-                "output_tokens": 500,
-                "total_tokens": 2000,
-            }
-        }
-    )
-
-    input_tokens: int = Field(default=0, description="Number of input/prompt tokens consumed")
-    output_tokens: int = Field(default=0, description="Number of output/completion tokens generated")
-    total_tokens: int = Field(default=0, description="Total tokens (input + output)")
-
-    def __add__(self, other: "TokenUsage") -> "TokenUsage":
-        """Allow aggregating token usage from multiple calls."""
-        return TokenUsage(
-            input_tokens=self.input_tokens + other.input_tokens,
-            output_tokens=self.output_tokens + other.output_tokens,
-            total_tokens=self.total_tokens + other.total_tokens,
-        )
+# Valid fact types for recall operations (excludes 'observation' which is internal)
+VALID_RECALL_FACT_TYPES = frozenset(["world", "experience", "opinion"])


 class DispositionTraits(BaseModel):
@@ -137,7 +54,6 @@ class MemoryFact(BaseModel):
                "metadata": {"source": "slack"},
                "chunk_id": "bank123_session_abc123_0",
                "activation": 0.95,
-                "tags": ["user_a", "session_123"],
            }
        }
    )
@@ -155,7 +71,6 @@ class MemoryFact(BaseModel):
    chunk_id: str | None = Field(
        None, description="ID of the chunk this fact was extracted from (format: bank_id_document_id_chunk_index)"
    )
-    tags: list[str] | None = Field(None, description="Visibility scope tags associated with this fact")


 class ChunkInfo(BaseModel):
@@ -232,7 +147,6 @@ class ReflectResult(BaseModel):
                },
                "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},
            }
        }
    )
@@ -246,26 +160,6 @@ class ReflectResult(BaseModel):
        default=None,
        description="Structured output parsed according to the provided response schema. Only present when response_schema was provided.",
    )
-    usage: TokenUsage | None = Field(
-        default=None,
-        description="Token usage metrics for the LLM calls made during this reflect operation.",
-    )
-    tool_trace: list[ToolCallTrace] = Field(
-        default_factory=list,
-        description="Trace of tool calls made during reflection. Only present when include.tool_calls is enabled.",
-    )
-    llm_trace: list[LLMCallTrace] = Field(
-        default_factory=list,
-        description="Trace of LLM calls made during reflection. Only present when include.tool_calls is enabled.",
-    )
-    mental_models: list[MentalModelRef] = Field(
-        default_factory=list,
-        description="Mental models accessed during reflection, including directives (subtype='directive').",
-    )
-    directives_applied: list[DirectiveRef] = Field(
-        default_factory=list,
-        description="Directive mental models that were applied during this reflection.",
-    )


 class Opinion(BaseModel):
@@ -329,32 +223,3 @@ class EntityState(BaseModel):
    observations: list[EntityObservation] = Field(
        default_factory=list, description="List of observations about this entity"
    )
-
-
-class MentalModel(BaseModel):
-    """
-    A manually configured mental model for tracking specific topics/areas.
-
-    Mental models are user-defined focus areas that the agent should track
-    and maintain summaries for, unlike auto-extracted entities.
-    """
-
-    model_config = ConfigDict(
-        json_schema_extra={
-            "example": {
-                "id": "team-dynamics",
-                "name": "Team Dynamics",
-                "description": "Track how the team collaborates, communication patterns, conflicts, and resolutions",
-                "summary": "The team has strong collaboration...",
-                "summary_updated_at": "2024-01-15T10:30:00Z",
-                "created_at": "2024-01-10T08:00:00Z",
-            }
-        }
-    )
-
-    id: str = Field(description="Unique identifier (alphanumeric lowercase)")
-    name: str = Field(description="Display name for the mental model")
-    description: str = Field(description="Prompt/directions for what to track and summarize")
-    summary: str | None = Field(None, description="Generated summary based on relevant facts")
-    summary_updated_at: str | None = Field(None, description="ISO format date when summary was last updated")
-    created_at: str = Field(description="ISO format date when the mental model was created")
@@ -1,5 +1,5 @@
 """
-bank profile utilities for disposition and mission management.
+bank profile utilities for disposition and background management.
 """

 import json
@@ -27,18 +27,19 @@ class BankProfile(TypedDict):

    name: str
    disposition: DispositionTraits
-    mission: str
+    background: str


-class MissionMergeResponse(BaseModel):
-    """LLM response for mission merge."""
+class BackgroundMergeResponse(BaseModel):
+    """LLM response for background merge with disposition inference."""

-    mission: str = Field(description="Merged mission in first person perspective")
+    background: str = Field(description="Merged background in first person perspective")
+    disposition: DispositionTraits = Field(description="Inferred disposition traits (skepticism, literalism, empathy)")


 async def get_bank_profile(pool, bank_id: str) -> BankProfile:
    """
-    Get bank profile (name, disposition + mission).
+    Get bank profile (name, disposition + background).
    Auto-creates bank with default values if not exists.

    Args:
@@ -46,13 +47,13 @@ async def get_bank_profile(pool, bank_id: str) -> BankProfile:
        bank_id: bank IDentifier

    Returns:
-        BankProfile with name, typed DispositionTraits, and mission
+        BankProfile with name, typed DispositionTraits, and background
    """
    async with acquire_with_retry(pool) as conn:
        # Try to get existing bank
        row = await conn.fetchrow(
            f"""
-            SELECT name, disposition, mission
+            SELECT name, disposition, background
            FROM {fq_table("banks")} WHERE bank_id = $1
            """,
            bank_id,
@@ -65,15 +66,13 @@ async def get_bank_profile(pool, bank_id: str) -> BankProfile:
                disposition_data = json.loads(disposition_data)

            return BankProfile(
-                name=row["name"],
-                disposition=DispositionTraits(**disposition_data),
-                mission=row["mission"] or "",
+                name=row["name"], disposition=DispositionTraits(**disposition_data), background=row["background"]
            )

        # Bank doesn't exist, create with defaults
        await conn.execute(
            f"""
-            INSERT INTO {fq_table("banks")} (bank_id, name, disposition, mission)
+            INSERT INTO {fq_table("banks")} (bank_id, name, disposition, background)
            VALUES ($1, $2, $3::jsonb, $4)
            ON CONFLICT (bank_id) DO NOTHING
            """,
@@ -83,7 +82,7 @@ async def get_bank_profile(pool, bank_id: str) -> BankProfile:
            "",
        )

-        return BankProfile(name=bank_id, disposition=DispositionTraits(**DEFAULT_DISPOSITION), mission="")
+        return BankProfile(name=bank_id, disposition=DispositionTraits(**DEFAULT_DISPOSITION), background="")


 async def update_bank_disposition(pool, bank_id: str, disposition: dict[str, int]) -> None:
@@ -111,121 +110,244 @@ async def update_bank_disposition(pool, bank_id: str, disposition: dict[str, int
        )


-async def set_bank_mission(pool, bank_id: str, mission: str) -> None:
+async def merge_bank_background(pool, llm_config, bank_id: str, new_info: str, update_disposition: bool = True) -> dict:
    """
-    Set bank mission (replacing any existing mission).
-
-    Args:
-        pool: Database connection pool
-        bank_id: bank IDentifier
-        mission: The mission text
-    """
-    # Ensure bank exists first
-    await get_bank_profile(pool, bank_id)
-
-    async with acquire_with_retry(pool) as conn:
-        await conn.execute(
-            f"""
-            UPDATE {fq_table("banks")}
-            SET mission = $2,
-                updated_at = NOW()
-            WHERE bank_id = $1
-            """,
-            bank_id,
-            mission,
-        )
-
-
-async def merge_bank_mission(pool, llm_config, bank_id: str, new_info: str) -> dict:
-    """
-    Merge new mission information with existing mission using LLM.
+    Merge new background information with existing background using LLM.
    Normalizes to first person ("I") and resolves conflicts.
+    Optionally infers disposition traits from the merged background.

    Args:
        pool: Database connection pool
-        llm_config: LLM configuration for mission merging
+        llm_config: LLM configuration for background merging
        bank_id: bank IDentifier
-        new_info: New mission information to add/merge
+        new_info: New background information to add/merge
+        update_disposition: If True, infer Big Five traits from background (default: True)

    Returns:
-        Dict with 'mission' (str) key
+        Dict with 'background' (str) and optionally 'disposition' (dict) keys
    """
    # Get current profile
    profile = await get_bank_profile(pool, bank_id)
-    current_mission = profile["mission"]
+    current_background = profile["background"]

-    # Use LLM to merge missions
-    result = await _llm_merge_mission(llm_config, current_mission, new_info)
+    # Use LLM to merge backgrounds and optionally infer disposition
+    result = await _llm_merge_background(llm_config, current_background, new_info, infer_disposition=update_disposition)

-    merged_mission = result["mission"]
+    merged_background = result["background"]
+    inferred_disposition = result.get("disposition")

    # Update in database
    async with acquire_with_retry(pool) as conn:
-        await conn.execute(
-            f"""
-            UPDATE {fq_table("banks")}
-            SET mission = $2,
-                updated_at = NOW()
-            WHERE bank_id = $1
-            """,
-            bank_id,
-            merged_mission,
-        )
+        if inferred_disposition:
+            # Update both background and disposition
+            await conn.execute(
+                f"""
+                UPDATE {fq_table("banks")}
+                SET background = $2,
+                    disposition = $3::jsonb,
+                    updated_at = NOW()
+                WHERE bank_id = $1
+                """,
+                bank_id,
+                merged_background,
+                json.dumps(inferred_disposition),
+            )
+        else:
+            # Update only background
+            await conn.execute(
+                f"""
+                UPDATE {fq_table("banks")}
+                SET background = $2,
+                    updated_at = NOW()
+                WHERE bank_id = $1
+                """,
+                bank_id,
+                merged_background,
+            )

-    return {"mission": merged_mission}
+    response = {"background": merged_background}
+    if inferred_disposition:
+        response["disposition"] = inferred_disposition
+
+    return response


-async def _llm_merge_mission(llm_config, current: str, new_info: str) -> dict:
+async def _llm_merge_background(llm_config, current: str, new_info: str, infer_disposition: bool = False) -> dict:
    """
-    Use LLM to intelligently merge mission information.
+    Use LLM to intelligently merge background information.
+    Optionally infer Big Five disposition traits from the merged background.

    Args:
        llm_config: LLM configuration to use
-        current: Current mission text
+        current: Current background text
        new_info: New information to merge
+        infer_disposition: If True, also infer disposition traits

    Returns:
-        Dict with 'mission' (str) key
+        Dict with 'background' (str) and optionally 'disposition' (dict) keys
    """
-    prompt = f"""You are helping maintain an agent's mission statement.
+    if infer_disposition:
+        prompt = f"""You are helping maintain a memory bank's background/profile and infer their disposition. You MUST respond with ONLY valid JSON.

-Current mission: {current if current else "(empty)"}
+Current background: {current if current else "(empty)"}

 New information to add: {new_info}

 Instructions:
-1. Merge the new information with the current mission
-2. If there are conflicts, the NEW information overwrites the old
+1. Merge the new information with the current background
+2. If there are conflicts (e.g., different birthplaces), the NEW information overwrites the old
+3. Keep additions that don't conflict
+4. Output in FIRST PERSON ("I") perspective
+5. Be concise - keep merged background under 500 characters
+6. Infer disposition traits from the merged background (each 1-5 integer):
+   - Skepticism: 1-5 (1=trusting, takes things at face value; 5=skeptical, questions everything)
+   - Literalism: 1-5 (1=flexible interpretation, reads between lines; 5=literal, exact interpretation)
+   - Empathy: 1-5 (1=detached, focuses on facts; 5=empathetic, considers emotional context)
+
+CRITICAL: You MUST respond with ONLY a valid JSON object. No markdown, no code blocks, no explanations. Just the JSON.
+
+Format:
+{{
+  "background": "the merged background text in first person",
+  "disposition": {{
+    "skepticism": 3,
+    "literalism": 3,
+    "empathy": 3
+  }}
+}}
+
+Trait inference examples:
+- "I'm a lawyer" → skepticism: 4, literalism: 5, empathy: 2
+- "I'm a therapist" → skepticism: 2, literalism: 2, empathy: 5
+- "I'm an engineer" → skepticism: 3, literalism: 4, empathy: 3
+- "I've been burned before by trusting people" → skepticism: 5, literalism: 3, empathy: 3
+- "I try to understand what people really mean" → skepticism: 3, literalism: 2, empathy: 4
+- "I take contracts very seriously" → skepticism: 4, literalism: 5, empathy: 2"""
+    else:
+        prompt = f"""You are helping maintain a memory bank's background/profile.
+
+Current background: {current if current else "(empty)"}
+
+New information to add: {new_info}
+
+Instructions:
+1. Merge the new information with the current background
+2. If there are conflicts (e.g., different birthplaces), the NEW information overwrites the old
 3. Keep additions that don't conflict
 4. Output in FIRST PERSON ("I") perspective
 5. Be concise - keep it under 500 characters
-6. Return ONLY the merged mission text, no explanations
+6. Return ONLY the merged background text, no explanations

-Merged mission:"""
+Merged background:"""

    try:
+        # Prepare messages
        messages = [{"role": "user", "content": prompt}]

+        if infer_disposition:
+            # Use structured output with Pydantic model for disposition inference
+            try:
+                parsed = await llm_config.call(
+                    messages=messages,
+                    response_format=BackgroundMergeResponse,
+                    scope="bank_background",
+                    temperature=0.3,
+                    max_completion_tokens=8192,
+                )
+                logger.info(f"Successfully got structured response: background={parsed.background[:100]}")
+
+                # Convert Pydantic model to dict format
+                return {"background": parsed.background, "disposition": parsed.disposition.model_dump()}
+            except Exception as e:
+                logger.warning(f"Structured output failed, falling back to manual parsing: {e}")
+                # Fall through to manual parsing below
+
+        # Manual parsing fallback or non-disposition merge
        content = await llm_config.call(
-            messages=messages, scope="bank_mission", temperature=0.3, max_completion_tokens=8192
+            messages=messages, scope="bank_background", temperature=0.3, max_completion_tokens=8192
        )

-        logger.info(f"LLM response for mission merge (first 500 chars): {content[:500]}")
+        logger.info(f"LLM response for background merge (first 500 chars): {content[:500]}")

-        merged = content.strip()
-        if not merged or merged.lower() in ["(empty)", "none", "n/a"]:
-            merged = new_info if new_info else ""
-        return {"mission": merged}
+        if infer_disposition:
+            # Parse JSON response - try multiple extraction methods
+            result = None
+
+            # Method 1: Direct parse
+            try:
+                result = json.loads(content)
+                logger.info("Successfully parsed JSON directly")
+            except json.JSONDecodeError:
+                pass
+
+            # Method 2: Extract from markdown code blocks
+            if result is None:
+                # Remove markdown code blocks
+                code_block_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", content, re.DOTALL)
+                if code_block_match:
+                    try:
+                        result = json.loads(code_block_match.group(1))
+                        logger.info("Successfully extracted JSON from markdown code block")
+                    except json.JSONDecodeError:
+                        pass
+
+            # Method 3: Find nested JSON structure
+            if result is None:
+                # Look for JSON object with nested structure
+                json_match = re.search(
+                    r'\{[^{}]*"background"[^{}]*"disposition"[^{}]*\{[^{}]*\}[^{}]*\}', content, re.DOTALL
+                )
+                if json_match:
+                    try:
+                        result = json.loads(json_match.group())
+                        logger.info("Successfully extracted JSON using nested pattern")
+                    except json.JSONDecodeError:
+                        pass
+
+            # All parsing methods failed - use fallback
+            if result is None:
+                logger.warning(f"Failed to extract JSON from LLM response. Raw content: {content[:200]}")
+                # Fallback: use new_info as background with default disposition
+                return {
+                    "background": new_info if new_info else current if current else "",
+                    "disposition": DEFAULT_DISPOSITION.copy(),
+                }
+
+            # Validate disposition values
+            disposition = result.get("disposition", {})
+            for key in ["skepticism", "literalism", "empathy"]:
+                if key not in disposition:
+                    disposition[key] = 3  # Default to neutral
+                else:
+                    # Clamp to [1, 5] and convert to int
+                    disposition[key] = max(1, min(5, int(disposition[key])))
+
+            result["disposition"] = disposition
+
+            # Ensure background exists
+            if "background" not in result or not result["background"]:
+                result["background"] = new_info if new_info else ""
+
+            return result
+        else:
+            # Just background merge
+            merged = content
+            if not merged or merged.lower() in ["(empty)", "none", "n/a"]:
+                merged = new_info if new_info else ""
+            return {"background": merged}

    except Exception as e:
-        logger.error(f"Error merging mission with LLM: {e}")
+        logger.error(f"Error merging background with LLM: {e}")
        # Fallback: just append new info
        if current:
            merged = f"{current} {new_info}".strip()
        else:
            merged = new_info

-        return {"mission": merged}
+        result = {"background": merged}
+        if infer_disposition:
+            result["disposition"] = DEFAULT_DISPOSITION.copy()
+        return result


 async def list_banks(pool) -> list:
@@ -236,12 +358,12 @@ async def list_banks(pool) -> list:
        pool: Database connection pool

    Returns:
-        List of dicts with bank_id, name, disposition, mission, created_at, updated_at
+        List of dicts with bank_id, name, disposition, background, created_at, updated_at
    """
    async with acquire_with_retry(pool) as conn:
        rows = await conn.fetch(
            f"""
-            SELECT bank_id, name, disposition, mission, created_at, updated_at
+            SELECT bank_id, name, disposition, background, created_at, updated_at
            FROM {fq_table("banks")}
            ORDER BY updated_at DESC
            """
@@ -259,7 +381,7 @@ async def list_banks(pool) -> list:
                    "bank_id": row["bank_id"],
                    "name": row["name"],
                    "disposition": disposition_data,
-                    "mission": row["mission"] or "",
+                    "background": row["background"],
                    "created_at": row["created_at"].isoformat() if row["created_at"] else None,
                    "updated_at": row["updated_at"].isoformat() if row["updated_at"] else None,
                }
@@ -14,9 +14,7 @@ from typing import Literal

 from pydantic import BaseModel, ConfigDict, Field, field_validator

-from ...config import get_config
 from ..llm_wrapper import LLMConfig, OutputTooLongError
-from ..response_models import TokenUsage


 def _infer_temporal_date(fact_text: str, event_date: datetime) -> str | None:
@@ -111,44 +109,22 @@ class Fact(BaseModel):


 class CausalRelation(BaseModel):
-    """Causal relationship from this fact to a previous fact (stored format)."""
+    """Causal relationship between facts."""

-    target_fact_index: int = Field(description="Index of the related fact in the facts array (0-based).")
-    relation_type: Literal["caused_by", "enabled_by", "prevented_by"] = Field(
-        description="How this fact relates to the target: "
-        "'caused_by' = this fact was caused by the target, "
-        "'enabled_by' = this fact was enabled by the target, "
-        "'prevented_by' = this fact was prevented by the target"
+    target_fact_index: int = Field(
+        description="Index of the related fact in the facts array (0-based). "
+        "This creates a directed causal link to another fact in the extraction."
    )
-    strength: float = Field(
-        description="Strength of relationship (0.0 to 1.0)",
-        ge=0.0,
-        le=1.0,
-        default=1.0,
-    )
-
-
-class FactCausalRelation(BaseModel):
-    """
-    Causal relationship from this fact to a PREVIOUS fact (embedded in each fact).
-
-    Uses index-based references but ONLY allows referencing facts that appear
-    BEFORE this fact in the list. This prevents hallucination of invalid indices.
-    """
-
-    target_index: int = Field(
-        description="Index of the PREVIOUS fact this relates to (0-based). "
-        "MUST be less than this fact's position in the list. "
-        "Example: if this is fact #5, target_index can only be 0, 1, 2, 3, or 4."
-    )
-    relation_type: Literal["caused_by", "enabled_by", "prevented_by"] = Field(
-        description="How this fact relates to the target fact: "
+    relation_type: Literal["causes", "caused_by", "enables", "prevents"] = Field(
+        description="Type of causal relationship: "
+        "'causes' = this fact directly causes the target fact, "
        "'caused_by' = this fact was caused by the target fact, "
-        "'enabled_by' = this fact was enabled by the target fact, "
-        "'prevented_by' = this fact was blocked/prevented by the target fact"
+        "'enables' = this fact enables/allows the target fact, "
+        "'prevents' = this fact prevents/blocks the target fact"
    )
    strength: float = Field(
-        description="Strength of relationship (0.0 to 1.0). 1.0 = strong, 0.5 = moderate",
+        description="Strength of causal relationship (0.0 to 1.0). "
+        "1.0 = direct/strong causation, 0.5 = moderate, 0.3 = weak/indirect",
        ge=0.0,
        le=1.0,
        default=1.0,
@@ -156,67 +132,16 @@ class FactCausalRelation(BaseModel):


 class ExtractedFact(BaseModel):
-    """A single extracted fact."""
+    """A single extracted fact with 5 required dimensions for comprehensive capture."""

    model_config = ConfigDict(
        json_schema_mode="validation",
        json_schema_extra={"required": ["what", "when", "where", "who", "why", "fact_type"]},
    )

-    what: str = Field(description="Core fact - concise but complete (1-2 sentences)")
-    when: str = Field(description="When it happened. 'N/A' if unknown.")
-    where: str = Field(description="Location if relevant. 'N/A' if none.")
-    who: str = Field(description="People involved with relationships. 'N/A' if general.")
-    why: str = Field(description="Context/significance if important. 'N/A' if obvious.")
-
-    fact_kind: str = Field(default="conversation", description="'event' or 'conversation'")
-    occurred_start: str | None = Field(default=None, description="ISO timestamp for events")
-    occurred_end: str | None = Field(default=None, description="ISO timestamp for event end")
-    fact_type: Literal["world", "assistant"] = Field(description="'world' or 'assistant'")
-    entities: list[Entity] | None = Field(default=None, description="People, places, concepts")
-    causal_relations: list[FactCausalRelation] | None = Field(
-        default=None, description="Links to previous facts (target_index < this fact's index)"
-    )
-
-    @field_validator("entities", mode="before")
-    @classmethod
-    def ensure_entities_list(cls, v):
-        """Ensure entities is always a list (convert None to empty list)."""
-        if v is None:
-            return []
-        return v
-
-    def build_fact_text(self) -> str:
-        """Combine all dimensions into a single comprehensive fact string."""
-        parts = [self.what]
-
-        # Add 'who' if not N/A
-        if self.who and self.who.upper() != "N/A":
-            parts.append(f"Involving: {self.who}")
-
-        # Add 'why' if not N/A
-        if self.why and self.why.upper() != "N/A":
-            parts.append(self.why)
-
-        if len(parts) == 1:
-            return parts[0]
-
-        return " | ".join(parts)
-
-
-class FactExtractionResponse(BaseModel):
-    """Response containing all extracted facts (causal relations are embedded in each fact)."""
-
-    facts: list[ExtractedFact] = Field(description="List of extracted factual statements")
-
-
-class ExtractedFactVerbose(BaseModel):
-    """A single extracted fact with verbose field descriptions for detailed extraction."""
-
-    model_config = ConfigDict(
-        json_schema_mode="validation",
-        json_schema_extra={"required": ["what", "when", "where", "who", "why", "fact_type"]},
-    )
+    # ==========================================================================
+    # FIVE REQUIRED DIMENSIONS - LLM must think about each one
+    # ==========================================================================

    what: str = Field(
        description="WHAT happened - COMPLETE, DETAILED description with ALL specifics. "
@@ -259,11 +184,16 @@ class ExtractedFactVerbose(BaseModel):
        "NOT: 'User liked it' or 'To help user'"
    )

+    # ==========================================================================
+    # CLASSIFICATION
+    # ==========================================================================
+
    fact_kind: str = Field(
        default="conversation",
        description="'event' = specific datable occurrence (set occurred dates), 'conversation' = general info (no occurred dates)",
    )

+    # Temporal fields - optional
    occurred_start: str | None = Field(
        default=None,
        description="WHEN the event happened (ISO timestamp). Only for fact_kind='event'. Leave null for conversations.",
@@ -273,76 +203,59 @@ class ExtractedFactVerbose(BaseModel):
        description="WHEN the event ended (ISO timestamp). Only for events with duration. Leave null for conversations.",
    )

+    # Classification (CRITICAL - required)
+    # Note: LLM uses "assistant" but we convert to "bank" for storage
    fact_type: Literal["world", "assistant"] = Field(
        description="'world' = about the user/others (background, experiences). 'assistant' = experience with the assistant."
    )

+    # Entities - extracted from fact content
    entities: list[Entity] | None = Field(
        default=None,
        description="Named entities, objects, AND abstract concepts from the fact. Include: people names, organizations, places, significant objects (e.g., 'coffee maker', 'car'), AND abstract concepts/themes (e.g., 'friendship', 'career growth', 'loss', 'celebration'). Extract anything that could help link related facts together.",
    )
-
-    causal_relations: list[FactCausalRelation] | None = Field(
-        default=None,
-        description="Causal links to PREVIOUS facts only. target_index MUST be less than this fact's position. "
-        "Example: fact #3 can only reference facts 0, 1, or 2. Max 2 relations per fact.",
+    causal_relations: list[CausalRelation] | None = Field(
+        default=None, description="Causal links to other facts. Can be null."
    )

    @field_validator("entities", mode="before")
    @classmethod
    def ensure_entities_list(cls, v):
+        """Ensure entities is always a list (convert None to empty list)."""
        if v is None:
            return []
        return v

-
-class FactExtractionResponseVerbose(BaseModel):
-    """Response for verbose fact extraction."""
-
-    facts: list[ExtractedFactVerbose] = Field(description="List of extracted factual statements")
-
-
-class ExtractedFactNoCausal(BaseModel):
-    """A single extracted fact WITHOUT causal relations (for when causal extraction is disabled)."""
-
-    model_config = ConfigDict(
-        json_schema_mode="validation",
-        json_schema_extra={"required": ["what", "when", "where", "who", "why", "fact_type"]},
-    )
-
-    # Same fields as ExtractedFact but without causal_relations
-    what: str = Field(description="WHAT happened - COMPLETE, DETAILED description with ALL specifics.")
-    when: str = Field(description="WHEN it happened - include temporal information if mentioned.")
-    where: str = Field(description="WHERE it happened - SPECIFIC locations if applicable.")
-    who: str = Field(description="WHO is involved - ALL people/entities with relationships.")
-    why: str = Field(description="WHY it matters - emotional, contextual, and motivational details.")
-
-    fact_kind: str = Field(
-        default="conversation",
-        description="'event' = specific datable occurrence, 'conversation' = general info",
-    )
-    occurred_start: str | None = Field(default=None, description="WHEN the event happened (ISO timestamp).")
-    occurred_end: str | None = Field(default=None, description="WHEN the event ended (ISO timestamp).")
-    fact_type: Literal["world", "assistant"] = Field(
-        description="'world' = about the user/others. 'assistant' = experience with assistant."
-    )
-    entities: list[Entity] | None = Field(
-        default=None,
-        description="Named entities, objects, and concepts from the fact.",
-    )
-
-    @field_validator("entities", mode="before")
+    @field_validator("causal_relations", mode="before")
    @classmethod
-    def ensure_entities_list(cls, v):
+    def ensure_causal_relations_list(cls, v):
+        """Ensure causal_relations is always a list (convert None to empty list)."""
        if v is None:
            return []
        return v

+    def build_fact_text(self) -> str:
+        """Combine all dimensions into a single comprehensive fact string."""
+        parts = [self.what]

-class FactExtractionResponseNoCausal(BaseModel):
-    """Response for fact extraction without causal relations."""
+        # Add 'who' if not N/A
+        if self.who and self.who.upper() != "N/A":
+            parts.append(f"Involving: {self.who}")

-    facts: list[ExtractedFactNoCausal] = Field(description="List of extracted factual statements")
+        # Add 'why' if not N/A
+        if self.why and self.why.upper() != "N/A":
+            parts.append(self.why)
+
+        if len(parts) == 1:
+            return parts[0]
+
+        return " | ".join(parts)
+
+
+class FactExtractionResponse(BaseModel):
+    """Response containing all extracted facts."""
+
+    facts: list[ExtractedFact] = Field(description="List of extracted factual statements")


 def chunk_text(text: str, max_chars: int) -> list[str]:
@@ -434,119 +347,39 @@ def _chunk_conversation(turns: list[dict], max_chars: int) -> list[str]:
    return chunks if chunks else [json.dumps(turns, ensure_ascii=False)]


-# =============================================================================
-# FACT EXTRACTION PROMPTS
-# =============================================================================
+async def _extract_facts_from_chunk(
+    chunk: str,
+    chunk_index: int,
+    total_chunks: int,
+    event_date: datetime,
+    context: str,
+    llm_config: "LLMConfig",
+    agent_name: str = None,
+    extract_opinions: bool = False,
+) -> list[dict[str, str]]:
+    """
+    Extract facts from a single chunk (internal helper for parallel processing).

-# 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.
+    Note: event_date parameter is kept for backward compatibility but not used in prompt.
+    The LLM extracts temporal information from the context string instead.
+    """
+    memory_bank_context = f"\n- Your name: {agent_name}" if agent_name and extract_opinions else ""

-LANGUAGE RULE (CRITICAL): Output facts in the EXACT SAME language as the input text. If input is Japanese, output Japanese. If input is Chinese, output Chinese. NEVER translate to English. Preserve original language completely.
+    # Determine which fact types to extract based on the flag
+    # Note: We use "assistant" in the prompt but convert to "bank" for storage
+    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."
+        )
+
+    prompt = f"""Extract facts from text into structured format with FOUR required dimensions - BE EXTREMELY DETAILED.

 {fact_types_instruction}

-══════════════════════════════════════════════════════════════════════════
-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
-══════════════════════════════════════════════════════════════════════════
-
-1. **what**: Core fact - concise but complete (1-2 sentences max)
-2. **when**: Temporal info if mentioned. "N/A" if none. Use day name when known.
-3. **where**: Location if relevant. "N/A" if none.
-4. **who**: People involved with relationships. "N/A" if just general info.
-5. **why**: Context/significance ONLY if important. "N/A" if obvious.
-
-CONCISENESS: Capture the essence, not every word. One good sentence beats three mediocre ones.
-
-══════════════════════════════════════════════════════════════════════════
-COREFERENCE RESOLUTION
-══════════════════════════════════════════════════════════════════════════
-
-Link generic references to names when both appear:
- "my roommate" + "Emily" → use "Emily (user's roommate)"
- "the manager" + "Sarah" → use "Sarah (the manager)"
-
-══════════════════════════════════════════════════════════════════════════
-CLASSIFICATION
-══════════════════════════════════════════════════════════════════════════
-
-fact_kind:
- "event": Specific datable occurrence (set occurred_start/end)
- "conversation": Ongoing state, preference, trait (no dates)
-
-fact_type:
- "world": About user's life, other people, external events
- "assistant": Interactions with assistant (requests, recommendations)
-
-══════════════════════════════════════════════════════════════════════════
-TEMPORAL HANDLING
-══════════════════════════════════════════════════════════════════════════
-
-Use "Event Date" from input as reference for relative dates.
- "yesterday" relative to Event Date, not today
- For events: set occurred_start AND occurred_end (same for point events)
- For conversation facts: NO occurred dates
-
-══════════════════════════════════════════════════════════════════════════
-ENTITIES
-══════════════════════════════════════════════════════════════════════════
-
-Include: people names, organizations, places, key objects, abstract concepts (career, friendship, etc.)
-Always include "user" when fact is about the user.
-
-══════════════════════════════════════════════════════════════════════════
-EXAMPLES
-══════════════════════════════════════════════════════════════════════════
-
-Example 1 - Selective extraction (Event Date: June 10, 2024):
-Input: "Hey! How's it going? Good morning! So I'm planning my wedding - want a small outdoor ceremony. Just got back from Emily's wedding, she married Sarah at a rooftop garden. It was nice weather. I grabbed a coffee on the way."
-
-Output: ONLY 2 facts (skip greetings, weather, coffee):
-1. what="User planning wedding, wants small outdoor ceremony", who="user", why="N/A", entities=["user", "wedding"]
-2. what="Emily married Sarah at rooftop garden", who="Emily (user's friend), Sarah", occurred_start="2024-06-09", entities=["Emily", "Sarah", "wedding"]
-
-Example 2 - Professional context:
-Input: "Alice has 5 years of Kubernetes experience and holds CKA certification. She's been leading the infrastructure team since March. By the way, she prefers dark roast coffee."
-
-Output: ONLY 2 facts (skip coffee preference - too trivial):
-1. what="Alice has 5 years Kubernetes experience, CKA certified", who="Alice", entities=["Alice", "Kubernetes", "CKA"]
-2. what="Alice leads infrastructure team since March", who="Alice", entities=["Alice", "infrastructure"]
-
-══════════════════════════════════════════════════════════════════════════
-QUALITY OVER QUANTITY
-══════════════════════════════════════════════════════════════════════════
-
-Ask: "Would this be useful to recall in 6 months?" If no, skip it."""
-
-
-# Verbose extraction prompt - detailed, comprehensive facts (legacy mode)
-VERBOSE_FACT_EXTRACTION_PROMPT = """Extract facts from text into structured format with FIVE required dimensions - BE EXTREMELY DETAILED.
-
-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 English if the input is in another language.
-
-{fact_types_instruction}

 ══════════════════════════════════════════════════════════════════════════
 FACT FORMAT - ALL FIVE DIMENSIONS REQUIRED - MAXIMUM VERBOSITY
@@ -640,88 +473,106 @@ FACT TYPE
  Include: what the user asked, what problem they wanted solved, what context they provided

 ══════════════════════════════════════════════════════════════════════════
-ENTITIES - EXTRACT EVERYTHING
+USER PREFERENCES (CRITICAL)
 ══════════════════════════════════════════════════════════════════════════

-Extract ALL of the following from the fact:
- People names (Emily, Alice, Dr. Smith)
- Organizations (Google, MIT, local coffee shop)
- Places (San Francisco, Brooklyn, Paris)
- Significant objects mentioned (coffee maker, new car, wedding dress)
- Abstract concepts/themes (friendship, career growth, loss, celebration)
+ALWAYS extract user preferences as separate facts! Watch for these keywords:
+- "enjoy", "like", "love", "prefer", "hate", "dislike", "favorite", "ideal", "dream", "want"

-ALWAYS include "user" when fact is about the user.
-Extract anything that could help link related facts together."""
-
-
-# Causal relationships section - appended when causal extraction is enabled
-CAUSAL_RELATIONSHIPS_SECTION = """
+Example: "I love Italian food and prefer outdoor dining"
+→ Fact 1: what="User loves Italian food", who="user", why="This is a food preference", entities=["user"]
+→ Fact 2: what="User prefers outdoor dining", who="user", why="This is a dining preference", entities=["user"]

 ══════════════════════════════════════════════════════════════════════════
-CAUSAL RELATIONSHIPS
+ENTITIES - INCLUDE PEOPLE, PLACES, OBJECTS, AND CONCEPTS (CRITICAL)
 ══════════════════════════════════════════════════════════════════════════

-Link facts with causal_relations (max 2 per fact). target_index must be < this fact's index.
-Types: "caused_by", "enabled_by", "prevented_by"
+Extract entities that help link related facts together. Include:
+1. "user" - when the fact is about the user
+2. People names - Emily, Dr. Smith, etc.
+3. Organizations/Places - IKEA, Goodwill, New York, etc.
+4. Specific objects - coffee maker, toaster, car, laptop, kitchen, etc.
+5. Abstract concepts - themes, values, emotions, or ideas that capture the essence of the fact:
+   - "friendship" for facts about friends helping each other, bonding, loyalty
+   - "career growth" for facts about promotions, learning new skills, job changes
+   - "loss" or "grief" for facts about death, endings, saying goodbye
+   - "celebration" for facts about parties, achievements, milestones
+   - "trust" or "betrayal" for facts involving those themes

-Example: "Lost job → couldn't pay rent → moved apartment"
- Fact 0: Lost job, causal_relations: null
- Fact 1: Couldn't pay rent, causal_relations: [{target_index: 0, relation_type: "caused_by"}]
- Fact 2: Moved apartment, causal_relations: [{target_index: 1, relation_type: "caused_by"}]"""
+✅ CORRECT: entities=["user", "coffee maker", "Goodwill", "kitchen"] for "User donated their coffee maker to Goodwill"
+✅ CORRECT: entities=["user", "Emily", "friendship"] for "Emily helped user move to a new apartment"
+✅ CORRECT: entities=["user", "promotion", "career growth"] for "User got promoted to senior engineer"
+✅ CORRECT: entities=["user", "grandmother", "loss", "grief"] for "User's grandmother passed away last week"
+❌ WRONG: entities=["user", "Emily"] only - missing the "friendship" concept that links to other friendship facts!

+══════════════════════════════════════════════════════════════════════════
+EXAMPLES
+══════════════════════════════════════════════════════════════════════════

-async def _extract_facts_from_chunk(
-    chunk: str,
-    chunk_index: int,
-    total_chunks: int,
-    event_date: datetime,
-    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).
+Example 1 - World Facts (Event Date: Tuesday, June 10, 2024):
+Input: "I'm planning my wedding and want a small outdoor ceremony. I just got back from my college roommate Emily's wedding - she married Sarah at a rooftop garden, it was so romantic!"

-    Note: event_date parameter is kept for backward compatibility but not used in prompt.
-    The LLM extracts temporal information from the context string instead.
-    """
-    memory_bank_context = f"\n- Your name: {agent_name}" if agent_name and extract_opinions else ""
+Output facts:

-    # Determine which fact types to extract based on the flag
-    # Note: We use "assistant" in the prompt but convert to "bank" for storage
-    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."
-        )
+1. User's wedding preference
+   - what: "User wants a small outdoor ceremony for their wedding"
+   - who: "user"
+   - why: "User prefers intimate outdoor settings"
+   - fact_type: "world", fact_kind: "conversation"
+   - entities: ["user", "wedding", "outdoor ceremony"]

-    # Check config for extraction mode and causal link extraction
-    config = get_config()
-    extraction_mode = config.retain_extraction_mode
-    extract_causal_links = config.retain_extract_causal_links
+2. User planning wedding
+   - what: "User is planning their own wedding"
+   - who: "user"
+   - why: "Inspired by Emily's ceremony"
+   - fact_type: "world", fact_kind: "conversation"
+   - entities: ["user", "wedding"]

-    # Select base prompt based on extraction mode
-    if extraction_mode == "verbose":
-        base_prompt = VERBOSE_FACT_EXTRACTION_PROMPT
-    else:
-        base_prompt = CONCISE_FACT_EXTRACTION_PROMPT
+3. Emily's wedding (THE EVENT - note occurred_start AND occurred_end both set)
+   - what: "Emily got married to Sarah at a rooftop garden ceremony in the city"
+   - who: "Emily (user's college roommate), Sarah (Emily's partner)"
+   - why: "User found it romantic and beautiful"
+   - fact_type: "world", fact_kind: "event"
+   - occurred_start: "2024-06-09T00:00:00Z" (recently, user "just got back" - relative to Event Date June 10, 2024)
+   - occurred_end: "2024-06-09T23:59:59Z" (same day - point event)
+   - entities: ["user", "Emily", "Sarah", "wedding", "rooftop garden"]

-    # Format the prompt with fact types instruction
-    prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
+Example 2 - Assistant Facts (Context: March 5, 2024):
+Input: "User: My API is really slow when we have 1000+ concurrent users. What can I do?
+Assistant: I'd recommend implementing Redis for caching frequently-accessed data, which should reduce your database load by 70-80%."

-    # Build the full prompt with or without causal relationships section
-    # Select appropriate response schema based on extraction mode and causal links
-    if extract_causal_links:
-        prompt = prompt + CAUSAL_RELATIONSHIPS_SECTION
-        if extraction_mode == "verbose":
-            response_schema = FactExtractionResponseVerbose
-        else:
-            response_schema = FactExtractionResponse
-    else:
-        response_schema = FactExtractionResponseNoCausal
+Output fact:
+   - what: "Assistant recommended implementing Redis for caching frequently-accessed data to improve API performance"
+   - when: "March 5, 2024 during conversation"
+   - who: "user, assistant"
+   - why: "User asked how to fix slow API performance with 1000+ concurrent users, expected 70-80% reduction in database load"
+   - fact_type: "assistant", fact_kind: "conversation"
+   - entities: ["user", "API", "Redis"]
+
+Example 3 - Kitchen Items with Concept Inference (Event Date: Thursday, May 30, 2024):
+Input: "I finally donated my old coffee maker to Goodwill. I upgraded to that new espresso machine last month and the old one was just taking up counter space."
+
+Output fact:
+   - what: "User donated their old coffee maker to Goodwill after upgrading to a new espresso machine"
+   - when: "Thursday, May 30, 2024"
+   - who: "user"
+   - why: "The old coffee maker was taking up counter space after the upgrade"
+   - fact_type: "world", fact_kind: "event"
+   - occurred_start: "2024-05-30T00:00:00Z" (uses Event Date year)
+   - occurred_end: "2024-05-30T23:59:59Z" (same day - point event)
+   - entities: ["user", "coffee maker", "Goodwill", "espresso machine", "kitchen"]
+
+Note: "kitchen" is inferred as a concept because coffee makers and espresso machines are kitchen appliances.
+This links the fact to other kitchen-related facts (toaster, faucet, kitchen mat, etc.) via the shared "kitchen" entity.
+
+Note how the "why" field captures the FULL STORY: what the user asked AND what outcome was expected!
+
+══════════════════════════════════════════════════════════════════════════
+WHAT TO EXTRACT vs SKIP
+══════════════════════════════════════════════════════════════════════════
+
+✅ EXTRACT: User preferences (ALWAYS as separate facts!), feelings, plans, events, relationships, achievements
+❌ SKIP: Greetings, filler ("thanks", "cool"), purely structural statements"""

    import logging

@@ -750,19 +601,16 @@ Context: {sanitized_context}
 Text:
 {sanitized_chunk}"""

-    usage = TokenUsage()  # Track cumulative usage across retries
    for attempt in range(max_retries):
        try:
-            extraction_response_json, call_usage = await llm_config.call(
+            extraction_response_json = await llm_config.call(
                messages=[{"role": "system", "content": prompt}, {"role": "user", "content": user_message}],
-                response_format=response_schema,
+                response_format=FactExtractionResponse,
                scope="memory_extract_facts",
                temperature=0.1,
-                max_completion_tokens=config.retain_max_completion_tokens,
+                max_completion_tokens=65000,
                skip_validation=True,  # Get raw JSON, we'll validate leniently
-                return_usage=True,
            )
-            usage = usage + call_usage  # Aggregate usage across retries

            # Lenient parsing of facts from raw JSON
            chunk_facts = []
@@ -780,10 +628,9 @@ Text:
                        f"LLM returned non-dict JSON after {max_retries} attempts: {type(extraction_response_json).__name__}. "
                        f"Raw: {str(extraction_response_json)[:500]}"
                    )
-                    return [], usage
+                    return []

            raw_facts = extraction_response_json.get("facts", [])
-
            if not raw_facts:
                logger.debug(
                    f"LLM response missing 'facts' field or returned empty list. "
@@ -898,40 +745,17 @@ Text:
                    if validated_entities:
                        fact_data["entities"] = validated_entities

-                # Add per-fact causal relations (only if enabled in config)
-                if extract_causal_links:
+                # Add causal relations if present (validate as CausalRelation objects)
+                # Filter out invalid relations (missing required fields)
+                causal_relations = get_value("causal_relations")
+                if causal_relations:
                    validated_relations = []
-                    causal_relations_raw = get_value("causal_relations")
-                    if causal_relations_raw:
-                        for rel in causal_relations_raw:
-                            if not isinstance(rel, dict):
-                                continue
-                            # New schema uses target_index
-                            target_idx = rel.get("target_index")
-                            relation_type = rel.get("relation_type")
-                            strength = rel.get("strength", 1.0)
-
-                            if target_idx is None or relation_type is None:
-                                continue
-
-                            # Validate: target_index must be < current fact index
-                            if target_idx < 0 or target_idx >= i:
-                                logger.debug(
-                                    f"Invalid target_index {target_idx} for fact {i} (must be 0 to {i - 1}). Skipping."
-                                )
-                                continue
-
+                    for rel in causal_relations:
+                        if isinstance(rel, dict) and "target_fact_index" in rel and "relation_type" in rel:
                            try:
-                                validated_relations.append(
-                                    CausalRelation(
-                                        target_fact_index=target_idx,
-                                        relation_type=relation_type,
-                                        strength=strength,
-                                    )
-                                )
+                                validated_relations.append(CausalRelation.model_validate(rel))
                            except Exception as e:
-                                logger.debug(f"Invalid causal relation {rel}: {e}")
-
+                                logger.warning(f"Invalid causal relation {rel}: {e}")
                    if validated_relations:
                        fact_data["causal_relations"] = validated_relations

@@ -954,7 +778,7 @@ Text:
                )
                continue

-            return chunk_facts, usage
+            return chunk_facts

        except BadRequestError as e:
            last_error = e
@@ -981,7 +805,7 @@ async def _extract_facts_with_auto_split(
    llm_config: LLMConfig,
    agent_name: str = None,
    extract_opinions: bool = False,
-) -> tuple[list[dict[str, str]], TokenUsage]:
+) -> list[dict[str, str]]:
    """
    Extract facts from a chunk with automatic splitting if output exceeds token limits.

@@ -999,7 +823,7 @@ async def _extract_facts_with_auto_split(
        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)
+        List of fact dictionaries extracted from the chunk (possibly from sub-chunks)
    """
    import logging

@@ -1078,14 +902,12 @@ async def _extract_facts_with_auto_split(

        # Combine results from both halves
        all_facts = []
-        total_usage = TokenUsage()
-        for sub_facts, sub_usage in sub_results:
-            all_facts.extend(sub_facts)
-            total_usage = total_usage + sub_usage
+        for sub_result in sub_results:
+            all_facts.extend(sub_result)

        logger.info(f"Successfully extracted {len(all_facts)} facts from split chunk {chunk_index + 1}")

-        return all_facts, total_usage
+        return all_facts


 async def extract_facts_from_text(
@@ -1095,7 +917,7 @@ async def extract_facts_from_text(
    agent_name: str,
    context: str = "",
    extract_opinions: bool = False,
-) -> tuple[list[Fact], list[tuple[str, int]], TokenUsage]:
+) -> tuple[list[Fact], list[tuple[str, int]]]:
    """
    Extract semantic facts from conversational or narrative text using LLM.

@@ -1114,22 +936,11 @@ async def extract_facts_from_text(
        extract_opinions: If True, extract ONLY opinions. If False, extract world and bank facts (no opinions)

    Returns:
-        Tuple of (facts, chunks, usage) where:
+        Tuple of (facts, chunks) where:
        - facts: List of Fact model instances
        - chunks: List of tuples (chunk_text, fact_count) for each chunk
-        - usage: Aggregated token usage across all LLM calls
    """
-    config = get_config()
-    chunks = chunk_text(text, max_chars=config.retain_chunk_size)
-
-    # Log chunk count before starting LLM requests
-    total_chars = sum(len(c) for c in chunks)
-    if len(chunks) > 1:
-        logger.debug(
-            f"[FACT_EXTRACTION] Text chunked into {len(chunks)} chunks ({total_chars:,} chars total, "
-            f"chunk_size={config.retain_chunk_size:,}) - starting parallel LLM extraction"
-        )
-
+    chunks = chunk_text(text, max_chars=3000)
    tasks = [
        _extract_facts_with_auto_split(
            chunk=chunk,
@@ -1146,12 +957,10 @@ async def extract_facts_from_text(
    chunk_results = await asyncio.gather(*tasks)
    all_facts = []
    chunk_metadata = []  # [(chunk_text, fact_count), ...]
-    total_usage = TokenUsage()
-    for chunk, (chunk_facts, chunk_usage) in zip(chunks, chunk_results):
+    for chunk, chunk_facts in zip(chunks, chunk_results):
        all_facts.extend(chunk_facts)
        chunk_metadata.append((chunk, len(chunk_facts)))
-        total_usage = total_usage + chunk_usage
-    return all_facts, chunk_metadata, total_usage
+    return all_facts, chunk_metadata


 # ============================================================================
@@ -1172,7 +981,7 @@ SECONDS_PER_FACT = 10

 async def extract_facts_from_contents(
    contents: list[RetainContent], llm_config, agent_name: str, extract_opinions: bool = False
-) -> tuple[list[ExtractedFactType], list[ChunkMetadata], TokenUsage]:
+) -> tuple[list[ExtractedFactType], list[ChunkMetadata]]:
    """
    Extract facts from multiple content items in parallel.

@@ -1189,10 +998,10 @@ async def extract_facts_from_contents(
        extract_opinions: If True, extract only opinions; otherwise world/bank facts

    Returns:
-        Tuple of (extracted_facts, chunks_metadata, usage)
+        Tuple of (extracted_facts, chunks_metadata)
    """
    if not contents:
-        return [], [], TokenUsage()
+        return [], []

    # Step 1: Create parallel fact extraction tasks
    fact_extraction_tasks = []
@@ -1215,15 +1024,11 @@ async def extract_facts_from_contents(
    # Step 3: Flatten and convert to typed objects
    extracted_facts: list[ExtractedFactType] = []
    chunks_metadata: list[ChunkMetadata] = []
-    total_usage = TokenUsage()

    global_chunk_idx = 0
    global_fact_idx = 0

-    for content_index, (content, (facts_from_llm, chunks_from_llm, content_usage)) in enumerate(
-        zip(contents, all_fact_results)
-    ):
-        total_usage = total_usage + content_usage
+    for content_index, (content, (facts_from_llm, chunks_from_llm)) in enumerate(zip(contents, all_fact_results)):
        chunk_start_idx = global_chunk_idx

        # Convert chunk tuples to ChunkMetadata objects
@@ -1268,7 +1073,6 @@ async def extract_facts_from_contents(
                        # mentioned_at: always the event_date (when the conversation/document occurred)
                        mentioned_at=content.event_date,
                        metadata=content.metadata,
-                        tags=content.tags,
                    )

                    extracted_facts.append(extracted_fact)
@@ -1278,7 +1082,7 @@ async def extract_facts_from_contents(
    # Step 4: Add time offsets to preserve ordering within each content
    _add_temporal_offsets(extracted_facts, contents)

-    return extracted_facts, chunks_metadata, total_usage
+    return extracted_facts, chunks_metadata


 def _parse_datetime(date_str: str):
@@ -45,7 +45,6 @@ async def insert_facts_batch(
    metadata_jsons = []
    chunk_ids = []
    document_ids = []
-    tags_list = []

    for fact in facts:
        fact_texts.append(fact.fact_text)
@@ -66,31 +65,16 @@ async def insert_facts_batch(
        chunk_ids.append(fact.chunk_id)
        # Use per-fact document_id if available, otherwise fallback to batch-level document_id
        document_ids.append(fact.document_id if fact.document_id else document_id)
-        # Convert tags to JSON string for proper batch insertion (PostgreSQL unnest doesn't handle 2D arrays well)
-        tags_list.append(json.dumps(fact.tags if fact.tags else []))

    # Batch insert all facts
-    # Note: tags are passed as JSON strings and converted back to varchar[] via jsonb_array_elements_text + array_agg
    results = await conn.fetch(
        f"""
-        WITH input_data AS (
-            SELECT * FROM unnest(
-                $2::text[], $3::vector[], $4::timestamptz[], $5::timestamptz[], $6::timestamptz[], $7::timestamptz[],
-                $8::text[], $9::text[], $10::float[], $11::int[], $12::jsonb[], $13::text[], $14::text[], $15::jsonb[]
-            ) AS t(text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
-                   context, fact_type, confidence_score, access_count, metadata, chunk_id, document_id, tags_json)
-        )
        INSERT INTO {fq_table("memory_units")} (bank_id, text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
-                                 context, fact_type, confidence_score, access_count, metadata, chunk_id, document_id, tags)
-        SELECT
-            $1,
-            text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
-            context, fact_type, confidence_score, access_count, metadata, chunk_id, document_id,
-            COALESCE(
-                (SELECT array_agg(elem) FROM jsonb_array_elements_text(tags_json) AS elem),
-                '{{}}'::varchar[]
-            )
-        FROM input_data
+                                 context, fact_type, confidence_score, access_count, metadata, chunk_id, document_id)
+        SELECT $1, * FROM unnest(
+            $2::text[], $3::vector[], $4::timestamptz[], $5::timestamptz[], $6::timestamptz[], $7::timestamptz[],
+            $8::text[], $9::text[], $10::float[], $11::int[], $12::jsonb[], $13::text[], $14::text[]
+        )
        RETURNING id
        """,
        bank_id,
@@ -107,7 +91,6 @@ async def insert_facts_batch(
        metadata_jsons,
        chunk_ids,
        document_ids,
-        tags_list,
    )

    unit_ids = [str(row["id"]) for row in results]
@@ -126,7 +109,7 @@ async def ensure_bank_exists(conn, bank_id: str) -> None:
    """
    await conn.execute(
        f"""
-        INSERT INTO {fq_table("banks")} (bank_id, disposition, mission)
+        INSERT INTO {fq_table("banks")} (bank_id, disposition, background)
        VALUES ($1, $2::jsonb, $3)
        ON CONFLICT (bank_id) DO UPDATE
        SET updated_at = NOW()
@@ -138,13 +121,7 @@ async def ensure_bank_exists(conn, bank_id: str) -> None:


 async def handle_document_tracking(
-    conn,
-    bank_id: str,
-    document_id: str,
-    combined_content: str,
-    is_first_batch: bool,
-    retain_params: dict | None = None,
-    document_tags: list[str] | None = None,
+    conn, bank_id: str, document_id: str, combined_content: str, is_first_batch: bool, retain_params: dict | None = None
 ) -> None:
    """
    Handle document tracking in the database.
@@ -156,7 +133,6 @@ async def handle_document_tracking(
        combined_content: Combined content text from all content items
        is_first_batch: Whether this is the first batch (for chunked operations)
        retain_params: Optional parameters passed during retain (context, event_date, etc.)
-        document_tags: Optional list of tags to associate with the document
    """
    import hashlib

@@ -173,14 +149,13 @@ async def handle_document_tracking(
    # Insert document (or update if exists from concurrent operations)
    await conn.execute(
        f"""
-        INSERT INTO {fq_table("documents")} (id, bank_id, original_text, content_hash, metadata, retain_params, tags)
-        VALUES ($1, $2, $3, $4, $5, $6, $7)
+        INSERT INTO {fq_table("documents")} (id, bank_id, original_text, content_hash, metadata, retain_params)
+        VALUES ($1, $2, $3, $4, $5, $6)
        ON CONFLICT (id, bank_id) DO UPDATE
        SET original_text = EXCLUDED.original_text,
            content_hash = EXCLUDED.content_hash,
            metadata = EXCLUDED.metadata,
            retain_params = EXCLUDED.retain_params,
-            tags = EXCLUDED.tags,
            updated_at = NOW()
        """,
        document_id,
@@ -189,5 +164,4 @@ async def handle_document_tracking(
        content_hash,
        json.dumps({}),  # Empty metadata dict
        json.dumps(retain_params) if retain_params else None,
-        document_tags or [],
    )
@@ -479,18 +479,14 @@ async def create_temporal_links_batch_per_fact(

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

        return len(links)
@@ -648,18 +644,14 @@ async def create_semantic_links_batch(

        if all_links:
            insert_start = time_mod.time()
-            # Batch inserts to avoid timeout on large batches
-            BATCH_SIZE = 1000
-            for batch_start in range(0, len(all_links), BATCH_SIZE):
-                batch = all_links[batch_start : batch_start + BATCH_SIZE]
-                await conn.executemany(
-                    f"""
-                    INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
-                    VALUES ($1, $2, $3, $4, $5)
-                    ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
-                    """,
-                    batch,
-                )
+            await conn.executemany(
+                f"""
+                INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
+                VALUES ($1, $2, $3, $4, $5)
+                ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
+                """,
+                all_links,
+            )
            _log(
                log_buffer, f"      [8.3] Insert {len(all_links)} semantic links: {time_mod.time() - insert_start:.3f}s"
            )
@@ -0,0 +1,254 @@
+"""
+Observation regeneration for retain pipeline.
+
+Regenerates entity observations as part of the retain transaction.
+"""
+
+import logging
+import time
+import uuid
+from datetime import UTC, datetime
+
+from ...config import get_config
+from ..memory_engine import fq_table
+from ..search import observation_utils
+from . import embedding_utils
+from .types import EntityLink
+
+logger = logging.getLogger(__name__)
+
+
+def utcnow():
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+# Simple dataclass-like container for facts (avoid importing from memory_engine)
+class MemoryFactForObservation:
+    def __init__(self, id: str, text: str, fact_type: str, context: str, occurred_start: str | None):
+        self.id = id
+        self.text = text
+        self.fact_type = fact_type
+        self.context = context
+        self.occurred_start = occurred_start
+
+
+async def regenerate_observations_batch(
+    conn, embeddings_model, llm_config, bank_id: str, entity_links: list[EntityLink], log_buffer: list[str] = None
+) -> None:
+    """
+    Regenerate observations for top entities in this batch.
+
+    Called INSIDE the retain transaction for atomicity - if observations
+    fail, the entire retain batch is rolled back.
+
+    Args:
+        conn: Database connection (from the retain transaction)
+        embeddings_model: Embeddings model for generating observation embeddings
+        llm_config: LLM configuration for observation extraction
+        bank_id: Bank identifier
+        entity_links: Entity links from this batch
+        log_buffer: Optional log buffer for timing
+    """
+    config = get_config()
+    TOP_N_ENTITIES = config.observation_top_entities
+    MIN_FACTS_THRESHOLD = config.observation_min_facts
+
+    if not entity_links:
+        return
+
+    # Count mentions per entity in this batch
+    entity_mention_counts: dict[str, int] = {}
+    for link in entity_links:
+        if link.entity_id:
+            entity_id = str(link.entity_id)
+            entity_mention_counts[entity_id] = entity_mention_counts.get(entity_id, 0) + 1
+
+    if not entity_mention_counts:
+        return
+
+    # Sort by mention count descending and take top N
+    sorted_entities = sorted(entity_mention_counts.items(), key=lambda x: x[1], reverse=True)
+    entities_to_process = [e[0] for e in sorted_entities[:TOP_N_ENTITIES]]
+
+    obs_start = time.time()
+
+    # Convert to UUIDs
+    entity_uuids = [uuid.UUID(eid) if isinstance(eid, str) else eid for eid in entities_to_process]
+
+    # Batch query for entity names
+    entity_rows = await conn.fetch(
+        f"""
+        SELECT id, canonical_name FROM {fq_table("entities")}
+        WHERE id = ANY($1) AND bank_id = $2
+        """,
+        entity_uuids,
+        bank_id,
+    )
+    entity_names = {row["id"]: row["canonical_name"] for row in entity_rows}
+
+    # Batch query for fact counts
+    fact_counts = await conn.fetch(
+        f"""
+        SELECT ue.entity_id, COUNT(*) as cnt
+        FROM {fq_table("unit_entities")} ue
+        JOIN {fq_table("memory_units")} mu ON ue.unit_id = mu.id
+        WHERE ue.entity_id = ANY($1) AND mu.bank_id = $2
+        GROUP BY ue.entity_id
+        """,
+        entity_uuids,
+        bank_id,
+    )
+    entity_fact_counts = {row["entity_id"]: row["cnt"] for row in fact_counts}
+
+    # Filter entities that meet the threshold
+    entities_with_names = []
+    for entity_id in entities_to_process:
+        entity_uuid = uuid.UUID(entity_id) if isinstance(entity_id, str) else entity_id
+        if entity_uuid not in entity_names:
+            continue
+        fact_count = entity_fact_counts.get(entity_uuid, 0)
+        if fact_count >= MIN_FACTS_THRESHOLD:
+            entities_with_names.append((entity_id, entity_names[entity_uuid]))
+
+    if not entities_with_names:
+        return
+
+    # Process entities SEQUENTIALLY (asyncpg doesn't allow concurrent queries on same connection)
+    # We must use the same connection to stay in the retain transaction
+    total_observations = 0
+
+    for entity_id, entity_name in entities_with_names:
+        try:
+            obs_ids = await _regenerate_entity_observations(
+                conn, embeddings_model, llm_config, bank_id, entity_id, entity_name
+            )
+            total_observations += len(obs_ids)
+        except Exception as e:
+            logger.error(f"[OBSERVATIONS] Error processing entity {entity_id}: {e}")
+
+    obs_time = time.time() - obs_start
+    if log_buffer is not None:
+        log_buffer.append(
+            f"[11] Observations: {total_observations} observations for {len(entities_with_names)} entities in {obs_time:.3f}s"
+        )
+
+
+async def _regenerate_entity_observations(
+    conn, embeddings_model, llm_config, bank_id: str, entity_id: str, entity_name: str
+) -> list[str]:
+    """
+    Regenerate observations for a single entity.
+
+    Uses the provided connection (part of retain transaction).
+
+    Args:
+        conn: Database connection (from the retain transaction)
+        embeddings_model: Embeddings model
+        llm_config: LLM configuration
+        bank_id: Bank identifier
+        entity_id: Entity UUID
+        entity_name: Canonical name of the entity
+
+    Returns:
+        List of created observation IDs
+    """
+    entity_uuid = uuid.UUID(entity_id) if isinstance(entity_id, str) else entity_id
+
+    # Get all facts mentioning this entity (exclude observations themselves)
+    rows = await conn.fetch(
+        f"""
+        SELECT mu.id, mu.text, mu.context, mu.occurred_start, mu.fact_type
+        FROM {fq_table("memory_units")} mu
+        JOIN {fq_table("unit_entities")} ue ON mu.id = ue.unit_id
+        WHERE mu.bank_id = $1
+          AND ue.entity_id = $2
+          AND mu.fact_type IN ('world', 'experience')
+        ORDER BY mu.occurred_start DESC
+        LIMIT 50
+        """,
+        bank_id,
+        entity_uuid,
+    )
+
+    if not rows:
+        return []
+
+    # Convert to fact objects for observation extraction
+    facts = []
+    for row in rows:
+        occurred_start = row["occurred_start"].isoformat() if row["occurred_start"] else None
+        facts.append(
+            MemoryFactForObservation(
+                id=str(row["id"]),
+                text=row["text"],
+                fact_type=row["fact_type"],
+                context=row["context"],
+                occurred_start=occurred_start,
+            )
+        )
+
+    # Extract observations using LLM
+    observations = await observation_utils.extract_observations_from_facts(llm_config, entity_name, facts)
+
+    if not observations:
+        return []
+
+    # Delete old observations for this entity
+    await conn.execute(
+        f"""
+        DELETE FROM {fq_table("memory_units")}
+        WHERE id IN (
+            SELECT mu.id
+            FROM {fq_table("memory_units")} mu
+            JOIN {fq_table("unit_entities")} ue ON mu.id = ue.unit_id
+            WHERE mu.bank_id = $1
+              AND mu.fact_type = 'observation'
+              AND ue.entity_id = $2
+        )
+        """,
+        bank_id,
+        entity_uuid,
+    )
+
+    # Generate embeddings for new observations
+    embeddings = await embedding_utils.generate_embeddings_batch(embeddings_model, observations)
+
+    # Insert new observations
+    current_time = utcnow()
+    created_ids = []
+
+    for obs_text, embedding in zip(observations, embeddings):
+        result = await conn.fetchrow(
+            f"""
+            INSERT INTO {fq_table("memory_units")} (
+                bank_id, text, embedding, context, event_date,
+                occurred_start, occurred_end, mentioned_at,
+                fact_type, access_count
+            )
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'observation', 0)
+            RETURNING id
+            """,
+            bank_id,
+            obs_text,
+            str(embedding),
+            f"observation about {entity_name}",
+            current_time,
+            current_time,
+            current_time,
+            current_time,
+        )
+        obs_id = str(result["id"])
+        created_ids.append(obs_id)
+
+        # Link observation to entity
+        await conn.execute(
+            f"""
+            INSERT INTO {fq_table("unit_entities")} (unit_id, entity_id)
+            VALUES ($1, $2)
+            """,
+            uuid.UUID(obs_id),
+            entity_uuid,
+        )
+
+    return created_ids
@@ -18,7 +18,6 @@ def utcnow():
    return datetime.now(UTC)


-from ..response_models import TokenUsage
 from . import (
    chunk_storage,
    deduplication,
@@ -27,8 +26,9 @@ from . import (
    fact_extraction,
    fact_storage,
    link_creation,
+    observation_regeneration,
 )
-from .types import EntityLink, ExtractedFact, ProcessedFact, RetainContent, RetainContentDict
+from .types import ExtractedFact, ProcessedFact, RetainContent, RetainContentDict

 logger = logging.getLogger(__name__)

@@ -38,6 +38,7 @@ async def retain_batch(
    embeddings_model,
    llm_config,
    entity_resolver,
+    task_backend,
    format_date_fn,
    duplicate_checker_fn,
    bank_id: str,
@@ -46,8 +47,7 @@ async def retain_batch(
    is_first_batch: bool = True,
    fact_type_override: str | None = None,
    confidence_score: float | None = None,
-    document_tags: list[str] | None = None,
-) -> tuple[list[list[str]], TokenUsage]:
+) -> list[list[str]]:
    """
    Process a batch of content through the retain pipeline.

@@ -56,6 +56,7 @@ async def retain_batch(
        embeddings_model: Embeddings model for generating embeddings
        llm_config: LLM configuration for fact extraction
        entity_resolver: Entity resolver for entity processing
+        task_backend: Task backend for background jobs
        format_date_fn: Function to format datetime to readable string
        duplicate_checker_fn: Function to check for duplicate facts
        bank_id: Bank identifier
@@ -64,10 +65,9 @@ async def retain_batch(
        is_first_batch: Whether this is the first batch
        fact_type_override: Override fact type for all facts
        confidence_score: Confidence score for opinions
-        document_tags: Tags applied to all items in this batch

    Returns:
-        Tuple of (unit ID lists, token usage for fact extraction)
+        List of unit ID lists (one list per content item)
    """
    start_time = time.time()
    total_chars = sum(len(item.get("content", "")) for item in contents_dicts)
@@ -86,16 +86,12 @@ async def retain_batch(
    # Convert dicts to RetainContent objects
    contents = []
    for item in contents_dicts:
-        # Merge item-level tags with document-level tags
-        item_tags = item.get("tags", []) or []
-        merged_tags = list(set(item_tags + (document_tags or [])))
        content = RetainContent(
            content=item["content"],
            context=item.get("context", ""),
            event_date=item.get("event_date") or utcnow(),
            metadata=item.get("metadata", {}),
            entities=item.get("entities", []),
-            tags=merged_tags,
        )
        contents.append(content)

@@ -103,7 +99,7 @@ async def retain_batch(
    step_start = time.time()
    extract_opinions = fact_type_override == "opinion"

-    extracted_facts, chunks, usage = await fact_extraction.extract_facts_from_contents(
+    extracted_facts, chunks = await fact_extraction.extract_facts_from_contents(
        contents, llm_config, agent_name, extract_opinions
    )
    log_buffer.append(
@@ -133,7 +129,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, document_tags
+                        conn, bank_id, document_id, combined_content, is_first_batch, retain_params
                    )
                else:
                    # Check for per-item document_ids
@@ -161,14 +157,14 @@ 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, document_tags
+                            conn, bank_id, doc_id, combined_content, is_first_batch, retain_params
                        )

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

    # Apply fact_type_override if provided
    if fact_type_override:
@@ -227,7 +223,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, document_tags
+                    conn, bank_id, document_id, combined_content, is_first_batch, retain_params
                )
                document_ids_added.append(document_id)
                doc_id_mapping[None] = document_id  # For backwards compatibility
@@ -271,13 +267,7 @@ async def retain_batch(
                                    retain_params["metadata"] = first_item["metadata"]

                            await fact_storage.handle_document_tracking(
-                                conn,
-                                bank_id,
-                                actual_doc_id,
-                                combined_content,
-                                is_first_batch,
-                                retain_params,
-                                document_tags,
+                                conn, bank_id, actual_doc_id, combined_content, is_first_batch, retain_params
                            )
                            document_ids_added.append(actual_doc_id)

@@ -354,7 +344,7 @@ async def retain_batch(
            non_duplicate_facts = deduplication.filter_duplicates(processed_facts, is_duplicate_flags)

            if not non_duplicate_facts:
-                return [[] for _ in contents], usage
+                return [[] for _ in contents]

            # Insert facts (document_id is now stored per-fact)
            step_start = time.time()
@@ -404,9 +394,17 @@ async def retain_batch(
            causal_link_count = await link_creation.create_causal_links_batch(conn, unit_ids, non_duplicate_facts)
            log_buffer.append(f"[10] Causal links: {causal_link_count} links in {time.time() - step_start:.3f}s")

+            # Regenerate observations INSIDE transaction for atomicity
+            await observation_regeneration.regenerate_observations_batch(
+                conn, embeddings_model, llm_config, bank_id, entity_links, log_buffer
+            )
+
            # Map results back to original content items
            result_unit_ids = _map_results_to_contents(contents, extracted_facts, is_duplicate_flags, unit_ids)

+        # Trigger background tasks AFTER transaction commits (opinion reinforcement only)
+        await _trigger_background_tasks(task_backend, bank_id, unit_ids, non_duplicate_facts)
+
        # Log final summary
        total_time = time.time() - start_time
        log_buffer.append(f"{'=' * 60}")
@@ -417,7 +415,7 @@ async def retain_batch(

        logger.info("\n" + "\n".join(log_buffer) + "\n")

-        return result_unit_ids, usage
+        return result_unit_ids


 def _map_results_to_contents(
@@ -448,3 +446,24 @@ def _map_results_to_contents(
        result_unit_ids.append(content_unit_ids)

    return result_unit_ids
+
+
+async def _trigger_background_tasks(
+    task_backend,
+    bank_id: str,
+    unit_ids: list[str],
+    facts: list[ProcessedFact],
+) -> None:
+    """Trigger opinion reinforcement as background task (after transaction commits)."""
+    # Trigger opinion reinforcement if there are entities
+    fact_entities = [[e.name for e in fact.entities] for fact in facts]
+    if any(fact_entities):
+        await task_backend.submit_task(
+            {
+                "type": "reinforce_opinion",
+                "bank_id": bank_id,
+                "created_unit_ids": unit_ids,
+                "unit_texts": [fact.fact_text for fact in facts],
+                "unit_entities": fact_entities,
+            }
+        )
@@ -21,7 +21,6 @@ class RetainContentDict(TypedDict, total=False):
        metadata: Custom key-value metadata (optional)
        document_id: Document ID for this content item (optional)
        entities: User-provided entities to merge with extracted entities (optional)
-        tags: Visibility scope tags for this content item (optional)
    """

    content: str  # Required
@@ -30,7 +29,6 @@ class RetainContentDict(TypedDict, total=False):
    metadata: dict[str, str]
    document_id: str
    entities: list[dict[str, str]]  # [{"text": "...", "type": "..."}]
-    tags: list[str]  # Visibility scope tags


 def _now_utc() -> datetime:
@@ -51,7 +49,6 @@ class RetainContent:
    event_date: datetime = field(default_factory=_now_utc)
    metadata: dict[str, str] = field(default_factory=dict)
    entities: list[dict[str, str]] = field(default_factory=list)  # User-provided entities
-    tags: list[str] = field(default_factory=list)  # Visibility scope tags


@dataclass
@@ -116,7 +113,6 @@ class ExtractedFact:
    context: str = ""
    mentioned_at: datetime | None = None
    metadata: dict[str, str] = field(default_factory=dict)
-    tags: list[str] = field(default_factory=list)  # Visibility scope tags


@dataclass
@@ -162,9 +158,6 @@ class ProcessedFact:
    # Track which content this fact came from (for user entity merging)
    content_index: int = 0

-    # Visibility scope tags
-    tags: list[str] = field(default_factory=list)
-
    @property
    def is_duplicate(self) -> bool:
        """Check if this fact was marked as a duplicate."""
@@ -208,7 +201,6 @@ class ProcessedFact:
            causal_relations=extracted_fact.causal_relations,
            chunk_id=chunk_id,
            content_index=extracted_fact.content_index,
-            tags=extracted_fact.tags,
        )


@@ -240,7 +232,6 @@ class RetainBatch:
    document_id: str | None = None
    fact_type_override: str | None = None
    confidence_score: float | None = None
-    document_tags: list[str] = field(default_factory=list)  # Tags applied to all items

    # Extracted data (populated during processing)
    extracted_facts: list[ExtractedFact] = field(default_factory=list)
@@ -11,8 +11,7 @@ from abc import ABC, abstractmethod

 from ..db_utils import acquire_with_retry
 from ..memory_engine import fq_table
-from .tags import TagsMatch, filter_results_by_tags
-from .types import MPFPTimings, RetrievalResult
+from .types import RetrievalResult

 logger = logging.getLogger(__name__)

@@ -43,10 +42,7 @@ class GraphRetriever(ABC):
        query_text: str | None = None,
        semantic_seeds: list[RetrievalResult] | None = None,
        temporal_seeds: list[RetrievalResult] | None = None,
-        adjacency=None,  # TypedAdjacency, optional pre-loaded graph
-        tags: list[str] | None = None,  # Visibility scope tags for filtering
-        tags_match: TagsMatch = "any",  # How to match tags: 'any' (OR) or 'all' (AND)
-    ) -> tuple[list[RetrievalResult], MPFPTimings | None]:
+    ) -> list[RetrievalResult]:
        """
        Retrieve relevant facts via graph traversal.

@@ -59,11 +55,9 @@ class GraphRetriever(ABC):
            query_text: Original query text (optional, for some strategies)
            semantic_seeds: Pre-computed semantic entry points (from semantic retrieval)
            temporal_seeds: Pre-computed temporal entry points (from temporal retrieval)
-            adjacency: Pre-loaded typed adjacency graph (optional, for MPFP)
-            tags: Optional list of tags for visibility filtering (OR matching)

        Returns:
-            Tuple of (List of RetrievalResult with activation scores, optional timing info)
+            List of RetrievalResult objects with activation scores set
        """
        pass

@@ -117,10 +111,7 @@ class BFSGraphRetriever(GraphRetriever):
        query_text: str | None = None,
        semantic_seeds: list[RetrievalResult] | None = None,
        temporal_seeds: list[RetrievalResult] | None = None,
-        adjacency=None,  # Not used by BFS
-        tags: list[str] | None = None,
-        tags_match: TagsMatch = "any",
-    ) -> tuple[list[RetrievalResult], MPFPTimings | None]:
+    ) -> list[RetrievalResult]:
        """
        Retrieve facts using BFS spreading activation.

@@ -131,14 +122,11 @@ class BFSGraphRetriever(GraphRetriever):
        4. Return visited nodes up to budget

        Note: BFS finds its own entry points via embedding search.
-        The semantic_seeds, temporal_seeds, and adjacency parameters are accepted
+        The semantic_seeds and temporal_seeds parameters are accepted
        for interface compatibility but not used.
        """
        async with acquire_with_retry(pool) as conn:
-            results = await self._retrieve_with_conn(
-                conn, query_embedding_str, bank_id, fact_type, budget, tags=tags, tags_match=tags_match
-            )
-            return results, None
+            return await self._retrieve_with_conn(conn, query_embedding_str, bank_id, fact_type, budget)

    async def _retrieve_with_conn(
        self,
@@ -147,46 +135,33 @@ class BFSGraphRetriever(GraphRetriever):
        bank_id: str,
        fact_type: str,
        budget: int,
-        tags: list[str] | None = None,
-        tags_match: TagsMatch = "any",
    ) -> list[RetrievalResult]:
        """Internal implementation with connection."""
-        from .tags import build_tags_where_clause_simple
-
-        tags_clause = build_tags_where_clause_simple(tags, 6, match=tags_match)
-        params = [query_embedding_str, bank_id, fact_type, self.entry_point_threshold, self.entry_point_limit]
-        if tags:
-            params.append(tags)

        # Step 1: Find entry points
        entry_points = await conn.fetch(
            f"""
            SELECT id, text, context, event_date, occurred_start, occurred_end,
-                   mentioned_at, access_count, embedding, fact_type, document_id, chunk_id, tags,
+                   mentioned_at, access_count, embedding, fact_type, document_id, chunk_id,
                   1 - (embedding <=> $1::vector) AS similarity
            FROM {fq_table("memory_units")}
            WHERE bank_id = $2
              AND embedding IS NOT NULL
              AND fact_type = $3
              AND (1 - (embedding <=> $1::vector)) >= $4
-              {tags_clause}
            ORDER BY embedding <=> $1::vector
            LIMIT $5
            """,
-            *params,
+            query_embedding_str,
+            bank_id,
+            fact_type,
+            self.entry_point_threshold,
+            self.entry_point_limit,
        )

        if not entry_points:
-            logger.debug(
-                f"[BFS] No entry points found for fact_type={fact_type} (tags={tags}, tags_match={tags_match})"
-            )
            return []

-        logger.debug(
-            f"[BFS] Found {len(entry_points)} entry points for fact_type={fact_type} "
-            f"(tags={tags}, tags_match={tags_match})"
-        )
-
        # Step 2: BFS spreading activation
        visited = set()
        results = []
@@ -217,7 +192,7 @@ class BFSGraphRetriever(GraphRetriever):
                    f"""
                    SELECT mu.id, mu.text, mu.context, mu.occurred_start, mu.occurred_end,
                           mu.mentioned_at, mu.access_count, mu.embedding, mu.fact_type,
-                           mu.document_id, mu.chunk_id, mu.tags,
+                           mu.document_id, mu.chunk_id,
                           ml.weight, ml.link_type, ml.from_unit_id
                    FROM {fq_table("memory_links")} ml
                    JOIN {fq_table("memory_units")} mu ON ml.to_unit_id = mu.id
@@ -257,8 +232,4 @@ class BFSGraphRetriever(GraphRetriever):
                            neighbor_result = RetrievalResult.from_db_row(dict(n))
                            queue.append((neighbor_result, new_activation))

-        # Apply tags filtering (BFS may traverse into memories that don't match tags criteria)
-        if tags:
-            results = filter_results_by_tags(results, tags, match=tags_match)
-
        return results
@@ -1,256 +0,0 @@
-"""
-Link Expansion graph retrieval.
-
-A simple, fast graph retrieval that expands from seeds via:
-1. Entity links: Find facts sharing entities with seeds (filtered by entity frequency)
-2. Causal links: Find facts causally linked to seeds (top-k by weight)
-
-Characteristics:
- 2-3 DB queries (seed finding + parallel entity/causal expansion)
- Sublinear: only touches connected facts via indexes
- No iteration, no propagation, no normalization
- Target: <100ms
-"""
-
-import logging
-import time
-
-from ..db_utils import acquire_with_retry
-from ..memory_engine import fq_table
-from .graph_retrieval import GraphRetriever
-from .tags import TagsMatch, filter_results_by_tags
-from .types import MPFPTimings, RetrievalResult
-
-logger = logging.getLogger(__name__)
-
-
-async def _find_semantic_seeds(
-    conn,
-    query_embedding_str: str,
-    bank_id: str,
-    fact_type: str,
-    limit: int = 20,
-    threshold: float = 0.3,
-    tags: list[str] | None = None,
-    tags_match: TagsMatch = "any",
-) -> list[RetrievalResult]:
-    """Find semantic seeds via embedding search."""
-    from .tags import build_tags_where_clause_simple
-
-    tags_clause = build_tags_where_clause_simple(tags, 6, match=tags_match)
-    params = [query_embedding_str, bank_id, fact_type, threshold, limit]
-    if tags:
-        params.append(tags)
-
-    rows = await conn.fetch(
-        f"""
-        SELECT id, text, context, event_date, occurred_start, occurred_end,
-               mentioned_at, access_count, embedding, fact_type, document_id, chunk_id, tags,
-               1 - (embedding <=> $1::vector) AS similarity
-        FROM {fq_table("memory_units")}
-        WHERE bank_id = $2
-          AND embedding IS NOT NULL
-          AND fact_type = $3
-          AND (1 - (embedding <=> $1::vector)) >= $4
-          {tags_clause}
-        ORDER BY embedding <=> $1::vector
-        LIMIT $5
-        """,
-        *params,
-    )
-    return [RetrievalResult.from_db_row(dict(r)) for r in rows]
-
-
-class LinkExpansionRetriever(GraphRetriever):
-    """
-    Graph retrieval via direct link expansion from seeds.
-
-    Expands through entity co-occurrence and causal links in a single query.
-    Fast and simple alternative to MPFP.
-    """
-
-    def __init__(
-        self,
-        max_entity_frequency: int = 500,
-        causal_weight_threshold: float = 0.3,
-        causal_limit_per_seed: int = 10,
-    ):
-        """
-        Initialize link expansion retriever.
-
-        Args:
-            max_entity_frequency: Skip entities appearing in more than this many facts
-            causal_weight_threshold: Minimum weight for causal links
-            causal_limit_per_seed: Max causal links to follow per seed
-        """
-        self.max_entity_frequency = max_entity_frequency
-        self.causal_weight_threshold = causal_weight_threshold
-        self.causal_limit_per_seed = causal_limit_per_seed
-
-    @property
-    def name(self) -> str:
-        return "link_expansion"
-
-    async def retrieve(
-        self,
-        pool,
-        query_embedding_str: str,
-        bank_id: str,
-        fact_type: str,
-        budget: int,
-        query_text: str | None = None,
-        semantic_seeds: list[RetrievalResult] | None = None,
-        temporal_seeds: list[RetrievalResult] | None = None,
-        adjacency=None,
-        tags: list[str] | None = None,
-        tags_match: TagsMatch = "any",
-    ) -> tuple[list[RetrievalResult], MPFPTimings | None]:
-        """
-        Retrieve facts by expanding links from seeds.
-
-        Args:
-            pool: Database connection pool
-            query_embedding_str: Query embedding (unused, kept for interface)
-            bank_id: Memory bank ID
-            fact_type: Fact type to filter
-            budget: Maximum results to return
-            query_text: Original query text (unused)
-            semantic_seeds: Pre-computed semantic entry points
-            temporal_seeds: Pre-computed temporal entry points
-            adjacency: Unused, kept for interface compatibility
-            tags: Optional list of tags for visibility filtering (OR matching)
-
-        Returns:
-            Tuple of (results, timings)
-        """
-        start_time = time.time()
-        timings = MPFPTimings(fact_type=fact_type)
-
-        # Use single connection for all queries to reduce pool pressure
-        # (queries are fast ~50ms each, connection acquisition is the bottleneck)
-        async with acquire_with_retry(pool) as conn:
-            # Find seeds if not provided
-            if semantic_seeds:
-                all_seeds = list(semantic_seeds)
-            else:
-                seeds_start = time.time()
-                all_seeds = await _find_semantic_seeds(
-                    conn,
-                    query_embedding_str,
-                    bank_id,
-                    fact_type,
-                    limit=20,
-                    threshold=0.3,
-                    tags=tags,
-                    tags_match=tags_match,
-                )
-                timings.seeds_time = time.time() - seeds_start
-                logger.debug(
-                    f"[LinkExpansion] Found {len(all_seeds)} semantic seeds for fact_type={fact_type} "
-                    f"(tags={tags}, tags_match={tags_match})"
-                )
-
-            # Add temporal seeds if provided
-            if temporal_seeds:
-                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})
-            timings.pattern_count = len(seed_ids)
-
-            # Run entity and causal expansion sequentially on same connection
-            query_start = time.time()
-
-            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.access_count, mu.embedding,
-                    mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                    COUNT(*)::float AS score
-                FROM {fq_table("unit_entities")} seed_ue
-                JOIN {fq_table("entities")} e ON seed_ue.entity_id = e.id
-                JOIN {fq_table("unit_entities")} other_ue ON seed_ue.entity_id = other_ue.entity_id
-                JOIN {fq_table("memory_units")} mu ON other_ue.unit_id = mu.id
-                WHERE seed_ue.unit_id = ANY($1::uuid[])
-                  AND e.mention_count < $2
-                  AND mu.id != ALL($1::uuid[])
-                  AND mu.fact_type = $3
-                GROUP BY mu.id
-                ORDER BY score DESC
-                LIMIT $4
-                """,
-                seed_ids,
-                self.max_entity_frequency,
-                fact_type,
-                budget,
-            )
-
-            causal_rows = await conn.fetch(
-                f"""
-                SELECT DISTINCT ON (mu.id)
-                    mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                    mu.occurred_end, mu.mentioned_at, mu.access_count, mu.embedding,
-                    mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                    ml.weight + 1.0 AS score
-                FROM {fq_table("memory_links")} ml
-                JOIN {fq_table("memory_units")} mu ON ml.to_unit_id = mu.id
-                WHERE ml.from_unit_id = ANY($1::uuid[])
-                  AND ml.link_type IN ('causes', 'caused_by', 'enables', 'prevents')
-                  AND ml.weight >= $2
-                  AND mu.fact_type = $3
-                ORDER BY mu.id, ml.weight DESC
-                LIMIT $4
-                """,
-                seed_ids,
-                self.causal_weight_threshold,
-                fact_type,
-                budget,
-            )
-
-            timings.edge_load_time = time.time() - query_start
-            timings.db_queries = 2
-            timings.edge_count = len(entity_rows) + len(causal_rows)
-
-        # Merge results, taking max score per fact
-        score_map: dict[str, float] = {}
-        row_map: dict[str, dict] = {}
-
-        for row in entity_rows:
-            fact_id = str(row["id"])
-            score_map[fact_id] = max(score_map.get(fact_id, 0), row["score"])
-            row_map[fact_id] = dict(row)
-
-        for row in causal_rows:
-            fact_id = str(row["id"])
-            score_map[fact_id] = max(score_map.get(fact_id, 0), row["score"])
-            if fact_id not in row_map:
-                row_map[fact_id] = dict(row)
-
-        # Sort by score and limit
-        sorted_ids = sorted(score_map.keys(), key=lambda x: score_map[x], reverse=True)[:budget]
-        rows = [row_map[fact_id] for fact_id in sorted_ids]
-
-        # Convert to results
-        results = []
-        for row in rows:
-            result = RetrievalResult.from_db_row(dict(row))
-            result.activation = row["score"]
-            results.append(result)
-
-        # Apply tags filtering (graph expansion may reach untagged memories)
-        if tags:
-            results = filter_results_by_tags(results, tags, match=tags_match)
-
-        timings.result_count = len(results)
-        timings.traverse = time.time() - start_time
-
-        logger.debug(
-            f"LinkExpansion: {len(results)} results from {len(seed_ids)} seeds "
-            f"in {timings.traverse * 1000:.1f}ms (query: {timings.edge_load_time * 1000:.1f}ms)"
-        )
-
-        return results, timings
@@ -9,7 +9,6 @@ propagation from Approximate PPR.

 Key properties:
 - Sublinear in graph size (threshold pruning bounds active nodes)
- Lazy edge loading: only loads edges for frontier nodes, not entire graph
 - Predefined patterns capture different retrieval intents
 - All patterns run in parallel, results fused via RRF
 - No LLM in the loop during traversal
@@ -23,8 +22,7 @@ from dataclasses import dataclass, field
 from ..db_utils import acquire_with_retry
 from ..memory_engine import fq_table
 from .graph_retrieval import GraphRetriever
-from .tags import TagsMatch
-from .types import MPFPTimings, RetrievalResult
+from .types import RetrievalResult

 logger = logging.getLogger(__name__)

@@ -43,27 +41,11 @@ class EdgeTarget:


@dataclass
-class EdgeCache:
-    """
-    Cache for lazily-loaded edges.
+class TypedAdjacency:
+    """Adjacency lists split by edge type."""

-    Grows per-hop as edges are loaded for frontier nodes.
-    Shared across patterns to avoid redundant loads.
-    Loads ALL edge types at once to minimize DB queries.
-    Thread-safe via asyncio lock to prevent redundant concurrent loads.
-    """
-
-    # edge_type -> from_node_id -> list of EdgeTarget
+    # edge_type -> from_node_id -> list of (to_node_id, weight)
    graphs: dict[str, dict[str, list[EdgeTarget]]] = field(default_factory=dict)
-    # Track which nodes have been fully loaded (all edge types)
-    _fully_loaded: set[str] = field(default_factory=set)
-    # Timing stats
-    db_queries: int = 0
-    edge_load_time: float = 0.0
-    # Detailed hop timing for debugging
-    hop_details: list[dict] = field(default_factory=list)
-    # Lock to prevent redundant concurrent loads
-    _lock: asyncio.Lock = field(default_factory=asyncio.Lock)

    def get_neighbors(self, edge_type: str, node_id: str) -> list[EdgeTarget]:
        """Get neighbors for a node via a specific edge type."""
@@ -81,31 +63,6 @@ class EdgeCache:

        return [EdgeTarget(node_id=n.node_id, weight=n.weight / total) for n in neighbors]

-    def is_fully_loaded(self, node_id: str) -> bool:
-        """Check if all edges for this node have been loaded."""
-        return node_id in self._fully_loaded
-
-    def get_uncached(self, node_ids: list[str]) -> list[str]:
-        """Get node IDs that haven't been fully loaded yet."""
-        return [n for n in node_ids if not self.is_fully_loaded(n)]
-
-    def add_all_edges(self, edges_by_type: dict[str, dict[str, list[EdgeTarget]]], all_queried: list[str]):
-        """
-        Add loaded edges to the cache (all edge types at once).
-
-        Args:
-            edges_by_type: Dict mapping edge_type -> from_node_id -> list of EdgeTarget
-            all_queried: All node IDs that were queried (marks them as fully loaded)
-        """
-        for edge_type, edges in edges_by_type.items():
-            if edge_type not in self.graphs:
-                self.graphs[edge_type] = {}
-            for node_id, neighbors in edges.items():
-                self.graphs[edge_type][node_id] = neighbors
-
-        # Mark all queried nodes as fully loaded (even if they have no edges)
-        self._fully_loaded.update(all_queried)
-

@dataclass
 class PatternResult:
@@ -152,249 +109,66 @@ class SeedNode:


 # -----------------------------------------------------------------------------
-# Lazy Edge Loading
+# Core Algorithm
 # -----------------------------------------------------------------------------


-async def load_all_edges_for_frontier(
-    pool,
-    node_ids: list[str],
-    top_k_per_type: int = 20,
-) -> dict[str, dict[str, list[EdgeTarget]]]:
-    """
-    Load top-k edges per (node, edge_type) for frontier nodes.
-
-    Uses a LATERAL join to efficiently fetch only the top-k edges per type,
-    avoiding loading hundreds of entity edges when only 20 are needed.
-
-    Requires composite index: (from_unit_id, link_type, weight DESC)
-
-    Args:
-        pool: Database connection pool
-        node_ids: Frontier node IDs to load edges for
-        top_k_per_type: Max edges to load per (node, link_type) pair
-
-    Returns:
-        Dict mapping edge_type -> from_node_id -> list of EdgeTarget
-    """
-    if not node_ids:
-        return {}
-
-    async with acquire_with_retry(pool) as conn:
-        # Use LATERAL join to get top-k per (from_node, link_type)
-        # This leverages the composite index for efficient early termination
-        rows = await conn.fetch(
-            f"""
-            WITH frontier(node_id) AS (SELECT unnest($1::uuid[]))
-            SELECT f.node_id as from_unit_id, lt.link_type, edges.to_unit_id, edges.weight
-            FROM frontier f
-            CROSS JOIN (VALUES ('semantic'), ('temporal'), ('entity'), ('causes'), ('caused_by')) AS lt(link_type)
-            CROSS JOIN LATERAL (
-                SELECT ml.to_unit_id, ml.weight
-                FROM {fq_table("memory_links")} ml
-                WHERE ml.from_unit_id = f.node_id
-                  AND ml.link_type = lt.link_type
-                  AND ml.weight >= 0.1
-                ORDER BY ml.weight DESC
-                LIMIT $2
-            ) edges
-            """,
-            node_ids,
-            top_k_per_type,
-        )
-
-    # Group by edge_type -> from_node -> neighbors
-    result: dict[str, dict[str, list[EdgeTarget]]] = defaultdict(lambda: defaultdict(list))
-    for row in rows:
-        edge_type = row["link_type"]
-        from_id = str(row["from_unit_id"])
-        to_id = str(row["to_unit_id"])
-        weight = row["weight"]
-        result[edge_type][from_id].append(EdgeTarget(node_id=to_id, weight=weight))
-
-    # Convert nested defaultdicts to regular dicts
-    return {edge_type: dict(edges) for edge_type, edges in result.items()}
-
-
-# -----------------------------------------------------------------------------
-# Core Algorithm (Async with Lazy Loading)
-# -----------------------------------------------------------------------------
-
-
-@dataclass
-class PatternState:
-    """State for a pattern traversal between hops."""
-
-    pattern: list[str]
-    hop_index: int
-    scores: dict[str, float]
-    frontier: dict[str, float]
-
-
-def _init_pattern_state(seeds: list[SeedNode], pattern: list[str]) -> PatternState:
-    """Initialize pattern state from seeds."""
-    if not seeds:
-        return PatternState(pattern=pattern, hop_index=0, scores={}, frontier={})
-
-    total_seed_score = sum(s.score for s in seeds)
-    if total_seed_score == 0:
-        total_seed_score = len(seeds)
-
-    frontier = {s.node_id: s.score / total_seed_score for s in seeds}
-    return PatternState(pattern=pattern, hop_index=0, scores={}, frontier=frontier)
-
-
-def _execute_hop(state: PatternState, cache: EdgeCache, config: MPFPConfig) -> set[str]:
-    """
-    Execute ONE hop of traversal, return frontier nodes for next hop.
-
-    This is a pure function that uses cached edges (no DB access).
-    Returns set of uncached nodes needed for next hop.
-    """
-    if state.hop_index >= len(state.pattern):
-        return set()
-
-    edge_type = state.pattern[state.hop_index]
-
-    # Collect active nodes above threshold
-    active_nodes = [node_id for node_id, mass in state.frontier.items() if mass >= config.threshold]
-    if not active_nodes:
-        state.frontier = {}
-        return set()
-
-    # Propagate mass using cached edges
-    next_frontier: dict[str, float] = {}
-    uncached_for_next: set[str] = set()
-
-    for node_id, mass in state.frontier.items():
-        if mass < config.threshold:
-            continue
-
-        # Keep α portion for this node
-        state.scores[node_id] = state.scores.get(node_id, 0) + config.alpha * mass
-
-        # Push (1-α) to neighbors
-        push_mass = (1 - config.alpha) * mass
-        neighbors = cache.get_normalized_neighbors(edge_type, node_id, config.top_k_neighbors)
-
-        for neighbor in neighbors:
-            next_frontier[neighbor.node_id] = next_frontier.get(neighbor.node_id, 0) + push_mass * neighbor.weight
-            # Track if we'll need edges for this node in the next hop
-            if not cache.is_fully_loaded(neighbor.node_id):
-                uncached_for_next.add(neighbor.node_id)
-
-    state.frontier = next_frontier
-    state.hop_index += 1
-
-    return uncached_for_next
-
-
-def _finalize_pattern(state: PatternState, config: MPFPConfig) -> PatternResult:
-    """Finalize pattern by adding remaining frontier mass to scores."""
-    for node_id, mass in state.frontier.items():
-        if mass >= config.threshold:
-            state.scores[node_id] = state.scores.get(node_id, 0) + mass
-
-    return PatternResult(pattern=state.pattern, scores=state.scores)
-
-
-async def mpfp_traverse_hop_synchronized(
-    pool,
-    pattern_jobs: list[tuple[list[SeedNode], list[str]]],
-    config: MPFPConfig,
-    cache: EdgeCache,
-) -> list[PatternResult]:
-    """
-    Execute ALL patterns with hop-synchronized edge loading.
-
-    Instead of running each pattern independently (causing multiple DB queries),
-    this function:
-    1. Runs hop 1 for ALL patterns (using pre-warmed seed edges)
-    2. Collects ALL unique hop-2 frontier nodes across patterns
-    3. Pre-warms hop-2 edges in ONE query
-    4. Runs hop 2 for ALL patterns
-
-    This reduces DB queries from O(patterns * hops) to O(hops).
-
-    Args:
-        pool: Database connection pool
-        pattern_jobs: List of (seeds, pattern) tuples
-        config: Algorithm parameters
-        cache: Shared edge cache (should be pre-warmed with seed edges)
-
-    Returns:
-        List of PatternResult for each pattern
-    """
-    import time
-
-    # Initialize all pattern states
-    states = [_init_pattern_state(seeds, pattern) for seeds, pattern in pattern_jobs]
-
-    # Determine max hops (all patterns should be same length, but be safe)
-    max_hops = max((len(p) for _, p in pattern_jobs), default=0)
-
-    # Detailed timing for debugging
-    hop_times: list[dict] = []
-
-    # Execute hop-by-hop across ALL patterns
-    for hop in range(max_hops):
-        hop_start = time.time()
-        hop_timing = {"hop": hop, "patterns_executed": 0, "uncached_count": 0, "load_time": 0.0}
-
-        # Execute this hop for all patterns, collect uncached nodes for next hop
-        all_uncached: set[str] = set()
-        exec_start = time.time()
-        for state in states:
-            if state.hop_index < len(state.pattern):
-                uncached = _execute_hop(state, cache, config)
-                all_uncached.update(uncached)
-                hop_timing["patterns_executed"] += 1
-        hop_timing["exec_time"] = time.time() - exec_start
-
-        # Pre-warm edges for ALL uncached nodes before next hop
-        hop_timing["uncached_count"] = len(all_uncached)
-        if all_uncached:
-            uncached_list = list(all_uncached - cache._fully_loaded)
-            hop_timing["uncached_after_filter"] = len(uncached_list)
-            if uncached_list:
-                load_start = time.time()
-                edges_by_type = await load_all_edges_for_frontier(pool, uncached_list, config.top_k_neighbors)
-                hop_timing["load_time"] = time.time() - load_start
-                cache.edge_load_time += hop_timing["load_time"]
-                cache.db_queries += 1
-                cache.add_all_edges(edges_by_type, uncached_list)
-                hop_timing["edges_loaded"] = sum(
-                    len(neighbors) for edges in edges_by_type.values() for neighbors in edges.values()
-                )
-
-        hop_timing["total_time"] = time.time() - hop_start
-        hop_times.append(hop_timing)
-
-    # Store hop timing details in cache for logging
-    cache.hop_details = hop_times
-
-    # Finalize all patterns
-    return [_finalize_pattern(state, config) for state in states]
-
-
-async def mpfp_traverse_async(
-    pool,
+def mpfp_traverse(
    seeds: list[SeedNode],
    pattern: list[str],
+    adjacency: TypedAdjacency,
    config: MPFPConfig,
-    cache: EdgeCache,
 ) -> PatternResult:
    """
-    Async Forward Push traversal with lazy edge loading.
+    Forward Push traversal following a meta-path pattern.

-    NOTE: For better performance with multiple patterns, use mpfp_traverse_hop_synchronized().
-    This function is kept for single-pattern use cases.
+    Args:
+        seeds: Entry point nodes with initial scores
+        pattern: Sequence of edge types to follow
+        adjacency: Typed adjacency structure
+        config: Algorithm parameters
+
+    Returns:
+        PatternResult with accumulated scores per node
    """
    if not seeds:
        return PatternResult(pattern=pattern, scores={})

-    results = await mpfp_traverse_hop_synchronized(pool, [(seeds, pattern)], config, cache)
-    return results[0] if results else PatternResult(pattern=pattern, scores={})
+    scores: dict[str, float] = {}
+
+    # Initialize frontier with seed masses (normalized)
+    total_seed_score = sum(s.score for s in seeds)
+    if total_seed_score == 0:
+        total_seed_score = len(seeds)  # fallback to uniform
+
+    frontier: dict[str, float] = {s.node_id: s.score / total_seed_score for s in seeds}
+
+    # Follow pattern hop by hop
+    for edge_type in pattern:
+        next_frontier: dict[str, float] = {}
+
+        for node_id, mass in frontier.items():
+            if mass < config.threshold:
+                continue
+
+            # Keep α portion for this node
+            scores[node_id] = scores.get(node_id, 0) + config.alpha * mass
+
+            # Push (1-α) to neighbors
+            push_mass = (1 - config.alpha) * mass
+            neighbors = adjacency.get_normalized_neighbors(edge_type, node_id, config.top_k_neighbors)
+
+            for neighbor in neighbors:
+                next_frontier[neighbor.node_id] = next_frontier.get(neighbor.node_id, 0) + push_mass * neighbor.weight
+
+        frontier = next_frontier
+
+    # Final frontier nodes get their remaining mass
+    for node_id, mass in frontier.items():
+        if mass >= config.threshold:
+            scores[node_id] = scores.get(node_id, 0) + mass
+
+    return PatternResult(pattern=pattern, scores=scores)


 def rrf_fusion(
@@ -436,6 +210,38 @@ def rrf_fusion(
 # -----------------------------------------------------------------------------


+async def load_typed_adjacency(pool, bank_id: str) -> TypedAdjacency:
+    """
+    Load all edges for a bank, split by edge type.
+
+    Single query, then organize in-memory for fast traversal.
+    """
+    async with acquire_with_retry(pool) as conn:
+        rows = await conn.fetch(
+            f"""
+            SELECT ml.from_unit_id, ml.to_unit_id, ml.link_type, ml.weight
+            FROM {fq_table("memory_links")} ml
+            JOIN {fq_table("memory_units")} mu ON ml.from_unit_id = mu.id
+            WHERE mu.bank_id = $1
+              AND ml.weight >= 0.1
+            ORDER BY ml.from_unit_id, ml.weight DESC
+            """,
+            bank_id,
+        )
+
+    graphs: dict[str, dict[str, list[EdgeTarget]]] = defaultdict(lambda: defaultdict(list))
+
+    for row in rows:
+        from_id = str(row["from_unit_id"])
+        to_id = str(row["to_unit_id"])
+        link_type = row["link_type"]
+        weight = row["weight"]
+
+        graphs[link_type][from_id].append(EdgeTarget(node_id=to_id, weight=weight))
+
+    return TypedAdjacency(graphs=dict(graphs))
+
+
 async def fetch_memory_units_by_ids(
    pool,
    node_ids: list[str],
@@ -449,7 +255,7 @@ async def fetch_memory_units_by_ids(
        rows = await conn.fetch(
            f"""
            SELECT id, text, context, event_date, occurred_start, occurred_end,
-                   mentioned_at, access_count, embedding, fact_type, document_id, chunk_id, tags
+                   mentioned_at, access_count, embedding, fact_type, document_id, chunk_id
            FROM {fq_table("memory_units")}
            WHERE id = ANY($1::uuid[])
              AND fact_type = $2
@@ -468,10 +274,10 @@ async def fetch_memory_units_by_ids(

 class MPFPGraphRetriever(GraphRetriever):
    """
-    Graph retrieval using Meta-Path Forward Push with lazy edge loading.
+    Graph retrieval using Meta-Path Forward Push.

    Runs predefined patterns in parallel from semantic and temporal seeds,
-    loading edges on-demand per hop instead of loading entire graph upfront.
+    then fuses results via RRF.
    """

    def __init__(self, config: MPFPConfig | None = None):
@@ -481,13 +287,8 @@ class MPFPGraphRetriever(GraphRetriever):
        Args:
            config: Algorithm configuration (uses defaults if None)
        """
-        if config is None:
-            # Read top_k_neighbors from global config
-            from ...config import get_config
-
-            global_config = get_config()
-            config = MPFPConfig(top_k_neighbors=global_config.mpfp_top_k_neighbors)
-        self.config = config
+        self.config = config or MPFPConfig()
+        self._adjacency_cache: dict[str, TypedAdjacency] = {}

    @property
    def name(self) -> str:
@@ -503,12 +304,9 @@ class MPFPGraphRetriever(GraphRetriever):
        query_text: str | None = None,
        semantic_seeds: list[RetrievalResult] | None = None,
        temporal_seeds: list[RetrievalResult] | None = None,
-        adjacency=None,  # Ignored - kept for interface compatibility
-        tags: list[str] | None = None,
-        tags_match: TagsMatch = "any",
-    ) -> tuple[list[RetrievalResult], MPFPTimings | None]:
+    ) -> list[RetrievalResult]:
        """
-        Retrieve facts using MPFP algorithm with lazy edge loading.
+        Retrieve facts using MPFP algorithm.

        Args:
            pool: Database connection pool
@@ -519,15 +317,12 @@ class MPFPGraphRetriever(GraphRetriever):
            query_text: Original query text (optional)
            semantic_seeds: Pre-computed semantic entry points
            temporal_seeds: Pre-computed temporal entry points
-            adjacency: Ignored (kept for interface compatibility)
-            tags: Optional list of tags for visibility filtering (OR matching)

        Returns:
-            Tuple of (List of RetrievalResult with activation scores, MPFPTimings)
+            List of RetrievalResult with activation scores
        """
-        import time
-
-        timings = MPFPTimings(fact_type=fact_type)
+        # Load typed adjacency (could cache per bank_id with TTL)
+        adjacency = await load_typed_adjacency(pool, bank_id)

        # Convert seeds to SeedNode format
        semantic_seed_nodes = self._convert_seeds(semantic_seeds, "similarity")
@@ -535,88 +330,54 @@ class MPFPGraphRetriever(GraphRetriever):

        # If no semantic seeds provided, fall back to finding our own
        if not semantic_seed_nodes:
-            seeds_start = time.time()
-            semantic_seed_nodes = await self._find_semantic_seeds(
-                pool, query_embedding_str, bank_id, fact_type, tags=tags, tags_match=tags_match
-            )
-            timings.seeds_time = time.time() - seeds_start
-            logger.debug(
-                f"[MPFP] Found {len(semantic_seed_nodes)} semantic seeds for fact_type={fact_type} (tags={tags}, tags_match={tags_match})"
-            )
+            semantic_seed_nodes = await self._find_semantic_seeds(pool, query_embedding_str, bank_id, fact_type)

-        # Collect all pattern jobs
-        pattern_jobs = []
+        # Run all patterns in parallel
+        tasks = []

        # Patterns from semantic seeds
        for pattern in self.config.patterns_semantic:
            if semantic_seed_nodes:
-                pattern_jobs.append((semantic_seed_nodes, pattern))
+                tasks.append(
+                    asyncio.to_thread(
+                        mpfp_traverse,
+                        semantic_seed_nodes,
+                        pattern,
+                        adjacency,
+                        self.config,
+                    )
+                )

        # Patterns from temporal seeds
        for pattern in self.config.patterns_temporal:
            if temporal_seed_nodes:
-                pattern_jobs.append((temporal_seed_nodes, pattern))
+                tasks.append(
+                    asyncio.to_thread(
+                        mpfp_traverse,
+                        temporal_seed_nodes,
+                        pattern,
+                        adjacency,
+                        self.config,
+                    )
+                )

-        if not pattern_jobs:
-            logger.debug(
-                f"[MPFP] No pattern jobs (semantic_seeds={len(semantic_seed_nodes)}, temporal_seeds={len(temporal_seed_nodes)})"
-            )
-            return [], timings
+        if not tasks:
+            return []

-        timings.pattern_count = len(pattern_jobs)
-
-        # Shared edge cache across all patterns
-        cache = EdgeCache()
-
-        # Pre-warm cache with ALL seed node edges BEFORE running patterns
-        # This prevents redundant DB queries at hop 1
-        all_seed_ids = list({s.node_id for seeds, _ in pattern_jobs for s in seeds})
-        if all_seed_ids:
-            import time as time_module
-
-            prewarm_start = time_module.time()
-            edges_by_type = await load_all_edges_for_frontier(pool, all_seed_ids, self.config.top_k_neighbors)
-            cache.edge_load_time += time_module.time() - prewarm_start
-            cache.db_queries += 1
-            cache.add_all_edges(edges_by_type, all_seed_ids)
-
-        # Run all patterns with HOP-SYNCHRONIZED edge loading
-        # This batches hop-2 edge loads across ALL patterns into ONE query
-        # Reduces DB queries from O(patterns * hops) to O(hops)
-        step_start = time.time()
-        pattern_results = await mpfp_traverse_hop_synchronized(pool, pattern_jobs, self.config, cache)
-        timings.traverse = time.time() - step_start
-
-        # Record edge loading stats from cache
-        timings.edge_count = sum(len(neighbors) for g in cache.graphs.values() for neighbors in g.values())
-        timings.db_queries = cache.db_queries
-        timings.edge_load_time = cache.edge_load_time
-        timings.hop_details = cache.hop_details
+        # Gather pattern results
+        pattern_results = await asyncio.gather(*tasks)

        # Fuse results
-        step_start = time.time()
        fused = rrf_fusion(pattern_results, top_k=budget)
-        timings.fusion = time.time() - step_start

        if not fused:
-            logger.debug(f"[MPFP] No fused results after RRF fusion (pattern_count={len(pattern_results)})")
-            return [], timings
+            return []

-        # Get top result IDs
+        # Get top result IDs (don't exclude seeds - they may be highly relevant)
        result_ids = [node_id for node_id, score in fused][:budget]

        # Fetch full details
-        step_start = time.time()
        results = await fetch_memory_units_by_ids(pool, result_ids, fact_type)
-        timings.fetch = time.time() - step_start
-
-        # Filter results by tags (graph traversal may have picked up unfiltered memories)
-        if tags:
-            from .tags import filter_results_by_tags
-
-            results = filter_results_by_tags(results, tags, match=tags_match)
-
-        timings.result_count = len(results)

        # Add activation scores from fusion
        score_map = {node_id: score for node_id, score in fused}
@@ -626,7 +387,7 @@ class MPFPGraphRetriever(GraphRetriever):
        # Sort by activation
        results.sort(key=lambda r: r.activation or 0, reverse=True)

-        return results, timings
+        return results

    def _convert_seeds(
        self,
@@ -654,17 +415,8 @@ class MPFPGraphRetriever(GraphRetriever):
        fact_type: str,
        limit: int = 20,
        threshold: float = 0.3,
-        tags: list[str] | None = None,
-        tags_match: TagsMatch = "any",
    ) -> list[SeedNode]:
        """Fallback: find semantic seeds via embedding search."""
-        from .tags import build_tags_where_clause_simple
-
-        tags_clause = build_tags_where_clause_simple(tags, 6, match=tags_match)
-        params = [query_embedding_str, bank_id, fact_type, threshold, limit]
-        if tags:
-            params.append(tags)
-
        async with acquire_with_retry(pool) as conn:
            rows = await conn.fetch(
                f"""
@@ -674,11 +426,14 @@ class MPFPGraphRetriever(GraphRetriever):
                  AND embedding IS NOT NULL
                  AND fact_type = $3
                  AND (1 - (embedding <=> $1::vector)) >= $4
-                  {tags_clause}
                ORDER BY embedding <=> $1::vector
                LIMIT $5
                """,
-                *params,
+                query_embedding_str,
+                bank_id,
+                fact_type,
+                threshold,
+                limit,
            )

        return [SeedNode(node_id=str(r["id"]), score=r["similarity"]) for r in rows]
@@ -0,0 +1,125 @@
+"""
+Observation utilities for generating entity observations from facts.
+
+Observations are objective facts synthesized from multiple memory facts
+about an entity, without personality influence.
+"""
+
+import logging
+
+from pydantic import BaseModel, Field
+
+from ..response_models import MemoryFact
+
+logger = logging.getLogger(__name__)
+
+
+class Observation(BaseModel):
+    """An observation about an entity."""
+
+    observation: str = Field(description="The observation text - a factual statement about the entity")
+
+
+class ObservationExtractionResponse(BaseModel):
+    """Response containing extracted observations."""
+
+    observations: list[Observation] = Field(default_factory=list, description="List of observations about the entity")
+
+
+def format_facts_for_observation_prompt(facts: list[MemoryFact]) -> str:
+    """Format facts as text for observation extraction prompt."""
+    import json
+
+    if not facts:
+        return "[]"
+    formatted = []
+    for fact in facts:
+        fact_obj = {"text": fact.text}
+
+        # Add context if available
+        if fact.context:
+            fact_obj["context"] = fact.context
+
+        # Add occurred_start if available
+        if fact.occurred_start:
+            fact_obj["occurred_at"] = fact.occurred_start
+
+        formatted.append(fact_obj)
+
+    return json.dumps(formatted, indent=2)
+
+
+def build_observation_prompt(
+    entity_name: str,
+    facts_text: str,
+) -> str:
+    """Build the observation extraction prompt for the LLM."""
+    return f"""Based on the following facts about "{entity_name}", generate a list of key observations.
+
+FACTS ABOUT {entity_name.upper()}:
+{facts_text}
+
+Your task: Synthesize the facts into clear, objective observations about {entity_name}.
+
+GUIDELINES:
+1. Each observation should be a factual statement about {entity_name}
+2. Combine related facts into single observations where appropriate
+3. Be objective - do not add opinions, judgments, or interpretations
+4. Focus on what we KNOW about {entity_name}, not what we assume
+5. Include observations about: identity, characteristics, roles, relationships, activities
+6. Write in third person (e.g., "John is..." not "I think John is...")
+7. If there are conflicting facts, note the most recent or most supported one
+
+EXAMPLES of good observations:
+- "John works at Google as a software engineer"
+- "John is detail-oriented and methodical in his approach"
+- "John collaborates frequently with Sarah on the AI project"
+- "John joined the company in 2023"
+
+EXAMPLES of bad observations (avoid these):
+- "John seems like a good person" (opinion/judgment)
+- "John probably likes his job" (assumption)
+- "I believe John is reliable" (first-person opinion)
+
+Generate 3-7 observations based on the available facts. If there are very few facts, generate fewer observations."""
+
+
+def get_observation_system_message() -> str:
+    """Get the system message for observation extraction."""
+    return "You are an objective observer synthesizing facts about an entity. Generate clear, factual observations without opinions or personality influence. Be concise and accurate."
+
+
+async def extract_observations_from_facts(llm_config, entity_name: str, facts: list[MemoryFact]) -> list[str]:
+    """
+    Extract observations from facts about an entity using LLM.
+
+    Args:
+        llm_config: LLM configuration to use
+        entity_name: Name of the entity to generate observations about
+        facts: List of facts mentioning the entity
+
+    Returns:
+        List of observation strings
+    """
+    if not facts:
+        return []
+
+    facts_text = format_facts_for_observation_prompt(facts)
+    prompt = build_observation_prompt(entity_name, facts_text)
+
+    try:
+        result = await llm_config.call(
+            messages=[
+                {"role": "system", "content": get_observation_system_message()},
+                {"role": "user", "content": prompt},
+            ],
+            response_format=ObservationExtractionResponse,
+            scope="memory_extract_observation",
+        )
+
+        observations = [op.observation for op in result.observations]
+        return observations
+
+    except Exception as e:
+        logger.warning(f"Failed to extract observations for {entity_name}: {str(e)}")
+        return []
@@ -44,7 +44,7 @@ class CrossEncoderReranker:
            await cross_encoder.initialize()
        self._initialized = True

-    async def rerank(self, query: str, candidates: list[MergedCandidate]) -> list[ScoredResult]:
+    def rerank(self, query: str, candidates: list[MergedCandidate]) -> list[ScoredResult]:
        """
        Rerank candidates using cross-encoder scores.

@@ -85,7 +85,7 @@ class CrossEncoderReranker:
            pairs.append([query, doc_text])

        # Get cross-encoder scores
-        scores = await self.cross_encoder.predict(pairs)
+        scores = self.cross_encoder.predict(pairs)

        # Normalize scores using sigmoid to [0, 1] range
        # Cross-encoder returns logits which can be negative
@@ -1,172 +0,0 @@
-"""
-Tags filtering utilities for retrieval.
-
-Provides SQL building functions for filtering memories by tags.
-Supports four matching modes via TagsMatch enum:
- "any": OR matching, includes untagged memories (default, backward compatible)
- "all": AND matching, includes untagged memories
- "any_strict": OR matching, excludes untagged memories
- "all_strict": AND matching, excludes untagged memories
-
-OR matching (any/any_strict): Memory matches if ANY of its tags overlap with request tags
-AND matching (all/all_strict): Memory matches if ALL request tags are present in its tags
-"""
-
-from typing import Literal
-
-TagsMatch = Literal["any", "all", "any_strict", "all_strict"]
-
-
-def _parse_tags_match(match: TagsMatch) -> tuple[str, bool]:
-    """
-    Parse TagsMatch into operator and include_untagged flag.
-
-    Returns:
-        Tuple of (operator, include_untagged)
-        - operator: "&&" for any/any_strict, "@>" for all/all_strict
-        - include_untagged: True for any/all, False for any_strict/all_strict
-    """
-    if match == "any":
-        return "&&", True
-    elif match == "all":
-        return "@>", True
-    elif match == "any_strict":
-        return "&&", False
-    elif match == "all_strict":
-        return "@>", False
-    else:
-        # Default to "any" behavior
-        return "&&", True
-
-
-def build_tags_where_clause(
-    tags: list[str] | None,
-    param_offset: int = 1,
-    table_alias: str = "",
-    match: TagsMatch = "any",
-) -> tuple[str, list, int]:
-    """
-    Build a SQL WHERE clause for filtering by tags.
-
-    Supports four matching modes:
-    - "any" (default): OR matching, includes untagged memories
-    - "all": AND matching, includes untagged memories
-    - "any_strict": OR matching, excludes untagged memories
-    - "all_strict": AND matching, excludes untagged memories
-
-    Args:
-        tags: List of tags to filter by. If None or empty, returns empty clause (no filtering).
-        param_offset: Starting parameter number for SQL placeholders (default 1).
-        table_alias: Optional table alias prefix (e.g., "mu." for "memory_units mu").
-        match: Matching mode. Defaults to "any".
-
-    Returns:
-        Tuple of (sql_clause, params, next_param_offset):
-        - sql_clause: SQL WHERE clause string
-        - params: List of parameter values to bind
-        - next_param_offset: Next available parameter number
-
-    Example:
-        >>> clause, params, next_offset = build_tags_where_clause(['user_a'], 3, 'mu.', 'any_strict')
-        >>> print(clause)  # "AND mu.tags IS NOT NULL AND mu.tags != '{}' AND mu.tags && $3"
-    """
-    if not tags:
-        return "", [], param_offset
-
-    column = f"{table_alias}tags" if table_alias else "tags"
-    operator, include_untagged = _parse_tags_match(match)
-
-    if include_untagged:
-        # Include untagged memories (NULL or empty array) OR matching tags
-        clause = f"AND ({column} IS NULL OR {column} = '{{}}' OR {column} {operator} ${param_offset})"
-    else:
-        # Strict: only memories with matching tags (exclude NULL and empty)
-        clause = f"AND {column} IS NOT NULL AND {column} != '{{}}' AND {column} {operator} ${param_offset}"
-
-    return clause, [tags], param_offset + 1
-
-
-def build_tags_where_clause_simple(
-    tags: list[str] | None,
-    param_num: int,
-    table_alias: str = "",
-    match: TagsMatch = "any",
-) -> str:
-    """
-    Build a simple SQL WHERE clause for tags filtering.
-
-    This is a convenience version that returns just the clause string,
-    assuming the caller will add the tags array to their params list.
-
-    Args:
-        tags: List of tags to filter by. If None or empty, returns empty string.
-        param_num: Parameter number to use in the clause.
-        table_alias: Optional table alias prefix.
-        match: Matching mode. Defaults to "any".
-
-    Returns:
-        SQL clause string or empty string.
-    """
-    if not tags:
-        return ""
-
-    column = f"{table_alias}tags" if table_alias else "tags"
-    operator, include_untagged = _parse_tags_match(match)
-
-    if include_untagged:
-        # Include untagged memories (NULL or empty array) OR matching tags
-        return f"AND ({column} IS NULL OR {column} = '{{}}' OR {column} {operator} ${param_num})"
-    else:
-        # Strict: only memories with matching tags (exclude NULL and empty)
-        return f"AND {column} IS NOT NULL AND {column} != '{{}}' AND {column} {operator} ${param_num}"
-
-
-def filter_results_by_tags(
-    results: list,
-    tags: list[str] | None,
-    match: TagsMatch = "any",
-) -> list:
-    """
-    Filter retrieval results by tags in Python (for post-processing).
-
-    Used when SQL filtering isn't possible (e.g., graph traversal results).
-
-    Args:
-        results: List of RetrievalResult objects with a 'tags' attribute.
-        tags: List of tags to filter by. If None or empty, returns all results.
-        match: Matching mode. Defaults to "any".
-
-    Returns:
-        Filtered list of results.
-    """
-    if not tags:
-        return results
-
-    _, include_untagged = _parse_tags_match(match)
-    is_any_match = match in ("any", "any_strict")
-
-    tags_set = set(tags)
-    filtered = []
-
-    for result in results:
-        result_tags = getattr(result, "tags", None)
-
-        # Check if untagged
-        is_untagged = result_tags is None or len(result_tags) == 0
-
-        if is_untagged:
-            if include_untagged:
-                filtered.append(result)
-            # else: skip untagged
-        else:
-            result_tags_set = set(result_tags)
-            if is_any_match:
-                # Any overlap
-                if result_tags_set & tags_set:
-                    filtered.append(result)
-            else:
-                # All tags must be present
-                if tags_set <= result_tags_set:
-                    filtered.append(result)
-
-    return filtered
@@ -3,13 +3,31 @@ Think operation utilities for formulating answers based on agent and world facts
 """

 import logging
+import re
 from datetime import datetime

+from pydantic import BaseModel, Field
+
 from ..response_models import DispositionTraits, MemoryFact

 logger = logging.getLogger(__name__)


+class Opinion(BaseModel):
+    """An opinion formed by the bank."""
+
+    opinion: str = Field(description="The opinion or perspective with reasoning included")
+    confidence: float = Field(description="Confidence score for this opinion (0.0 to 1.0, where 1.0 is very confident)")
+
+
+class OpinionExtractionResponse(BaseModel):
+    """Response containing extracted opinions."""
+
+    opinions: list[Opinion] = Field(
+        default_factory=list, description="List of opinions formed with their supporting reasons and confidence scores"
+    )
+
+
 def describe_trait_level(value: int) -> str:
    """Convert trait value (1-5) to descriptive text."""
    levels = {1: "very low", 2: "low", 3: "moderate", 4: "high", 5: "very high"}
@@ -75,46 +93,17 @@ def format_facts_for_prompt(facts: list[MemoryFact]) -> str:
    return json.dumps(formatted, indent=2)


-def format_entity_summaries_for_prompt(entities: dict) -> str:
-    """Format entity summaries for inclusion in the reflect prompt.
-
-    Args:
-        entities: Dict mapping entity name to EntityState objects
-
-    Returns:
-        Formatted string with entity summaries, or empty string if no summaries
-    """
-    if not entities:
-        return ""
-
-    summaries = []
-    for name, state in entities.items():
-        # Get summary from observations (summary is stored as single observation)
-        if state.observations:
-            summary_text = state.observations[0].text
-            summaries.append(f"## {name}\n{summary_text}")
-
-    if not summaries:
-        return ""
-
-    return "\n\n".join(summaries)
-
-
 def build_think_prompt(
    agent_facts_text: str,
    world_facts_text: str,
+    opinion_facts_text: str,
    query: str,
    name: str,
    disposition: DispositionTraits,
    background: str,
    context: str | None = None,
-    entity_summaries_text: str | None = None,
 ) -> str:
-    """Build the think prompt for the LLM.
-
-    Note: opinion_facts_text parameter removed - opinions are now stored as mental models
-    and included via entity_summaries_text.
-    """
+    """Build the think prompt for the LLM."""
    disposition_desc = build_disposition_description(disposition)

    name_section = f"""
@@ -136,14 +125,6 @@ Your background:
 ADDITIONAL CONTEXT:
 {context}

-"""
-
-    entity_section = ""
-    if entity_summaries_text:
-        entity_section = f"""
-KEY PEOPLE, PLACES & THINGS I KNOW ABOUT:
-{entity_summaries_text}
-
 """

    return f"""Here's what I know and have experienced:
@@ -154,11 +135,14 @@ MY IDENTITY & EXPERIENCES:
 WHAT I KNOW ABOUT THE WORLD:
 {world_facts_text}

-{entity_section}{context_section}{name_section}{disposition_desc}{background_section}
+MY EXISTING OPINIONS & BELIEFS:
+{opinion_facts_text}
+
+{context_section}{name_section}{disposition_desc}{background_section}

 QUESTION: {query}

-Based on everything I know, believe, and who I am (including my name, disposition and background), here's what I genuinely think about this question. I'll draw on my experiences, knowledge, and personal traits to give you my honest perspective."""
+Based on everything I know, believe, and who I am (including my name, disposition and background), here's what I genuinely think about this question. I'll draw on my experiences, knowledge, opinions, and personal traits to give you my honest perspective."""


 def get_system_message(disposition: DispositionTraits) -> str:
@@ -188,7 +172,117 @@ def get_system_message(disposition: DispositionTraits) -> str:
        " ".join(instructions) if instructions else "Balance your disposition traits when interpreting information."
    )

-    return f"You are a person with your own thoughts, experiences, opinions, and disposition. When asked a question, respond naturally like a human would - share what you genuinely think based on what you know and have experienced. {disposition_instruction} Be direct, express your views confidently, and use 'I think', 'I believe', 'in my view', etc. Respond in plain text without markdown formatting. IMPORTANT: Detect the language of the question and respond in the SAME language. Do not translate to English if the question is in another language."
+    return f"You are a person with your own thoughts, experiences, opinions, and disposition. When asked a question, respond naturally like a human would - share what you genuinely think based on what you know and have experienced. {disposition_instruction} Be direct, express your views confidently, and use 'I think', 'I believe', 'in my view', etc. Respond in plain text without markdown formatting."
+
+
+async def extract_opinions_from_text(llm_config, text: str, query: str) -> list[Opinion]:
+    """
+    Extract opinions with reasons and confidence from text using LLM.
+
+    Args:
+        llm_config: LLM configuration to use
+        text: Text to extract opinions from
+        query: The original query that prompted this response
+
+    Returns:
+        List of Opinion objects with text and confidence
+    """
+    extraction_prompt = f"""Extract any NEW opinions or perspectives from the answer below and rewrite them in FIRST-PERSON as if YOU are stating the opinion directly.
+
+ORIGINAL QUESTION:
+{query}
+
+ANSWER PROVIDED:
+{text}
+
+Your task: Find opinions in the answer and rewrite them AS IF YOU ARE THE ONE SAYING THEM.
+
+An opinion is a judgment, viewpoint, or conclusion that goes beyond just stating facts.
+
+IMPORTANT: Do NOT extract statements like:
+- "I don't have enough information"
+- "The facts don't contain information about X"
+- "I cannot answer because..."
+
+ONLY extract actual opinions about substantive topics.
+
+CRITICAL FORMAT REQUIREMENTS:
+1. **ALWAYS start with first-person phrases**: "I think...", "I believe...", "In my view...", "I've come to believe...", "Previously I thought... but now..."
+2. **NEVER use third-person**: Do NOT say "The speaker thinks..." or "They believe..." - always use "I"
+3. Include the reasoning naturally within the statement
+4. Provide a confidence score (0.0 to 1.0)
+
+CORRECT Examples (✓ FIRST-PERSON):
+- "I think Alice is more reliable because she consistently delivers on time and writes clean code"
+- "Previously I thought all engineers were equal, but now I feel that experience and track record really matter"
+- "I believe reliability is best measured by consistent output over time"
+- "I've come to believe that track records are more important than potential"
+
+WRONG Examples (✗ THIRD-PERSON - DO NOT USE):
+- "The speaker thinks Alice is more reliable"
+- "They believe reliability matters"
+- "It is believed that Alice is better"
+
+If no genuine opinions are expressed (e.g., the response just says "I don't know"), return an empty list."""
+
+    try:
+        result = await llm_config.call(
+            messages=[
+                {
+                    "role": "system",
+                    "content": "You are converting opinions from text into first-person statements. Always use 'I think', 'I believe', 'I feel', etc. NEVER use third-person like 'The speaker' or 'They'.",
+                },
+                {"role": "user", "content": extraction_prompt},
+            ],
+            response_format=OpinionExtractionResponse,
+            scope="memory_extract_opinion",
+        )
+
+        # Format opinions with confidence score and convert to first-person
+        formatted_opinions = []
+        for op in result.opinions:
+            # Convert third-person to first-person if needed
+            opinion_text = op.opinion
+
+            # Replace common third-person patterns with first-person
+            def singularize_verb(verb):
+                if verb.endswith("es"):
+                    return verb[:-1]  # believes -> believe
+                elif verb.endswith("s"):
+                    return verb[:-1]  # thinks -> think
+                return verb
+
+            # Pattern: "The speaker/user [verb]..." -> "I [verb]..."
+            match = re.match(
+                r"^(The speaker|The user|They|It is believed) (believes?|thinks?|feels?|says|asserts?|considers?)(\s+that)?(.*)$",
+                opinion_text,
+                re.IGNORECASE,
+            )
+            if match:
+                verb = singularize_verb(match.group(2))
+                that_part = match.group(3) or ""  # Keep " that" if present
+                rest = match.group(4)
+                opinion_text = f"I {verb}{that_part}{rest}"
+
+            # If still doesn't start with first-person, prepend "I believe that "
+            first_person_starters = [
+                "I think",
+                "I believe",
+                "I feel",
+                "In my view",
+                "I've come to believe",
+                "Previously I",
+            ]
+            if not any(opinion_text.startswith(starter) for starter in first_person_starters):
+                opinion_text = "I believe that " + opinion_text[0].lower() + opinion_text[1:]
+
+            formatted_opinions.append(Opinion(opinion=opinion_text, confidence=op.confidence))
+
+        return formatted_opinions
+
+    except Exception as e:
+        logger.warning(f"Failed to extract opinions: {str(e)}")
+        return []


 async def reflect(
@@ -196,6 +290,7 @@ async def reflect(
    query: str,
    experience_facts: list[str] = None,
    world_facts: list[str] = None,
+    opinion_facts: list[str] = None,
    name: str = "Assistant",
    disposition: DispositionTraits = None,
    background: str = "",
@@ -212,6 +307,7 @@ async def reflect(
        query: Question to answer
        experience_facts: List of experience/agent fact strings
        world_facts: List of world fact strings
+        opinion_facts: List of opinion fact strings
        name: Name of the agent/persona
        disposition: Disposition traits (defaults to neutral)
        background: Background information
@@ -232,15 +328,18 @@ async def reflect(

    agent_results = to_memory_facts(experience_facts or [], "experience")
    world_results = to_memory_facts(world_facts or [], "world")
+    opinion_results = to_memory_facts(opinion_facts or [], "opinion")

    # Format facts for prompt
    agent_facts_text = format_facts_for_prompt(agent_results)
    world_facts_text = format_facts_for_prompt(world_results)
+    opinion_facts_text = format_facts_for_prompt(opinion_results)

    # Build prompt
    prompt = build_think_prompt(
        agent_facts_text=agent_facts_text,
        world_facts_text=world_facts_text,
+        opinion_facts_text=opinion_facts_text,
        query=query,
        name=name,
        disposition=disposition,
@@ -11,13 +11,6 @@ from typing import Any, Literal
 from pydantic import BaseModel, Field


-class TemporalConstraint(BaseModel):
-    """Detected temporal constraint from query analysis."""
-
-    start: datetime | None = Field(default=None, description="Start of temporal range")
-    end: datetime | None = Field(default=None, description="End of temporal range")
-
-
 class QueryInfo(BaseModel):
    """Information about the search query."""

@@ -26,11 +19,6 @@ class QueryInfo(BaseModel):
    timestamp: datetime = Field(description="When the query was executed")
    budget: int = Field(description="Maximum nodes to explore")
    max_tokens: int = Field(description="Maximum tokens to return in results")
-    tags: list[str] | None = Field(default=None, description="Tags filter applied to recall")
-    tags_match: str | None = Field(default=None, description="Tags matching mode: any, all, any_strict, all_strict")
-    temporal_constraint: TemporalConstraint | None = Field(
-        default=None, description="Detected temporal range from query"
-    )


 class EntryPoint(BaseModel):
@@ -22,7 +22,6 @@ from .trace import (
    SearchPhaseMetrics,
    SearchSummary,
    SearchTrace,
-    TemporalConstraint,
    WeightComponents,
 )

@@ -46,14 +45,7 @@ class SearchTracer:
        json_output = trace.to_json()
    """

-    def __init__(
-        self,
-        query: str,
-        budget: int,
-        max_tokens: int,
-        tags: list[str] | None = None,
-        tags_match: str | None = None,
-    ):
+    def __init__(self, query: str, budget: int, max_tokens: int):
        """
        Initialize tracer.

@@ -61,14 +53,10 @@ class SearchTracer:
            query: Search query text
            budget: Maximum nodes to explore
            max_tokens: Maximum tokens to return in results
-            tags: Tags filter applied to recall
-            tags_match: Tags matching mode (any, all, any_strict, all_strict)
        """
        self.query_text = query
        self.budget = budget
        self.max_tokens = max_tokens
-        self.tags = tags
-        self.tags_match = tags_match

        # Trace data
        self.query_embedding: list[float] | None = None
@@ -78,9 +66,6 @@ class SearchTracer:
        self.pruned: list[PruningDecision] = []
        self.phase_metrics: list[SearchPhaseMetrics] = []

-        # Temporal constraint detected from query
-        self.temporal_constraint: TemporalConstraint | None = None
-
        # New 4-way retrieval tracking
        self.retrieval_results: list[RetrievalMethodResults] = []
        self.rrf_merged: list[RRFMergeResult] = []
@@ -103,11 +88,6 @@ class SearchTracer:
        """Record the query embedding."""
        self.query_embedding = embedding

-    def record_temporal_constraint(self, start: datetime | None, end: datetime | None):
-        """Record the detected temporal constraint from query analysis."""
-        if start is not None or end is not None:
-            self.temporal_constraint = TemporalConstraint(start=start, end=end)
-
    def add_entry_point(self, node_id: str, text: str, similarity: float, rank: int):
        """
        Record an entry point.
@@ -448,9 +428,6 @@ class SearchTracer:
            timestamp=datetime.now(UTC),
            budget=self.budget,
            max_tokens=self.max_tokens,
-            tags=self.tags,
-            tags_match=self.tags_match,
-            temporal_constraint=self.temporal_constraint,
        )

        # Create summary
@@ -10,24 +10,6 @@ from datetime import datetime
 from typing import Any


-@dataclass
-class MPFPTimings:
-    """Timing breakdown for a single MPFP retrieval call."""
-
-    fact_type: str
-    edge_count: int = 0  # Total edges loaded
-    db_queries: int = 0  # Number of DB queries for edge loading
-    edge_load_time: float = 0.0  # Time spent loading edges from DB
-    traverse: float = 0.0  # Total traversal time (includes edge loading)
-    pattern_count: int = 0  # Number of patterns executed
-    fusion: float = 0.0  # Time for RRF fusion
-    fetch: float = 0.0  # Time to fetch memory unit details
-    seeds_time: float = 0.0  # Time to find semantic seeds (if fallback used)
-    result_count: int = 0  # Number of results returned
-    # Detailed per-hop timing: list of {hop, exec_time, uncached, load_time, edges_loaded, total_time}
-    hop_details: list[dict] = field(default_factory=list)
-
-
@dataclass
 class RetrievalResult:
    """
@@ -48,7 +30,6 @@ class RetrievalResult:
    chunk_id: str | None = None
    access_count: int = 0
    embedding: list[float] | None = None
-    tags: list[str] | None = None  # Visibility scope tags

    # Retrieval-specific scores (only one will be set depending on retrieval method)
    similarity: float | None = None  # Semantic retrieval
@@ -73,7 +54,6 @@ class RetrievalResult:
            chunk_id=row.get("chunk_id"),
            access_count=row.get("access_count", 0),
            embedding=row.get("embedding"),
-            tags=row.get("tags"),
            similarity=row.get("similarity"),
            bm25_score=row.get("bm25_score"),
            activation=row.get("activation"),
@@ -158,7 +138,6 @@ class ScoredResult:
            "chunk_id": self.retrieval.chunk_id,
            "access_count": self.retrieval.access_count,
            "embedding": self.retrieval.embedding,
-            "tags": self.retrieval.tags,
            "semantic_similarity": self.retrieval.similarity,
            "bm25_score": self.retrieval.bm25_score,
        }
@@ -1,40 +1,31 @@
 """
-Task backend for distributed task processing.
+Abstract task backend for running async tasks.

-This provides an abstraction for task storage and execution:
- BrokerTaskBackend: Uses PostgreSQL as broker (production)
- SyncTaskBackend: Executes tasks immediately (testing/embedded)
+This provides an abstraction that can be adapted to different execution models:
+- AsyncIO queue (default implementation)
+- Pub/Sub architectures (future)
+- Message brokers (future)
 """

-import json
+import asyncio
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    import asyncpg
+from typing import Any

 logger = logging.getLogger(__name__)


-def fq_table(table: str, schema: str | None = None) -> str:
-    """Get fully-qualified table name with optional schema prefix."""
-    if schema:
-        return f'"{schema}".{table}'
-    return table
-
-
 class TaskBackend(ABC):
    """
    Abstract base class for task execution backends.

    Implementations must:
    1. Store/publish task events (as serializable dicts)
-    2. Execute tasks through a provided executor callback (optional)
+    2. Execute tasks through a provided executor callback

    The backend treats tasks as pure dictionaries that can be serialized
-    and stored in the database. The executor (typically MemoryEngine.execute_task)
+    and sent over the network. The executor (typically MemoryEngine.execute_task)
    receives the dict and routes it to the appropriate handler.
    """

@@ -55,7 +46,7 @@ class TaskBackend(ABC):
    @abstractmethod
    async def initialize(self):
        """
-        Initialize the backend (e.g., connect to database).
+        Initialize the backend (e.g., start workers, connect to broker).
        """
        pass

@@ -72,7 +63,7 @@ class TaskBackend(ABC):
    @abstractmethod
    async def shutdown(self):
        """
-        Shutdown the backend gracefully.
+        Shutdown the backend gracefully (e.g., stop workers, close connections).
        """
        pass

@@ -102,8 +93,9 @@ class SyncTaskBackend(TaskBackend):
    """
    Synchronous task backend that executes tasks immediately.

-    This is useful for tests and embedded/CLI usage where we don't want
-    background workers. Tasks are executed inline rather than being queued.
+    This is useful for embedded/CLI usage where we don't want background
+    workers that prevent clean exit. Tasks are executed inline rather than
+    being queued.
    """

    async def initialize(self):
@@ -129,123 +121,130 @@ class SyncTaskBackend(TaskBackend):
        logger.debug("SyncTaskBackend shutdown")


-class BrokerTaskBackend(TaskBackend):
+class AsyncIOQueueBackend(TaskBackend):
    """
-    Task backend using PostgreSQL as broker.
+    Task backend implementation using asyncio queues.

-    submit_task() stores task_payload in async_operations table.
-    Actual polling and execution is handled separately by WorkerPoller.
-
-    This backend is used by the API to store tasks. Workers poll
-    the database separately to claim and execute tasks.
+    This is the default implementation that uses in-process asyncio queues
+    and a periodic consumer worker.
    """

-    def __init__(
-        self,
-        pool_getter: Callable[[], "asyncpg.Pool"],
-        schema: str | None = None,
-    ):
+    def __init__(self, batch_size: int = 100, batch_interval: float = 1.0):
        """
-        Initialize the broker task backend.
+        Initialize AsyncIO queue backend.

        Args:
-            pool_getter: Callable that returns the asyncpg connection pool
-            schema: Database schema for multi-tenant support (optional)
+            batch_size: Maximum number of tasks to process in one batch
+            batch_interval: Maximum time (seconds) to wait before processing batch
        """
        super().__init__()
-        self._pool_getter = pool_getter
-        self._schema = schema
+        self._queue: asyncio.Queue | None = None
+        self._worker_task: asyncio.Task | None = None
+        self._shutdown_event: asyncio.Event | None = None
+        self._batch_size = batch_size
+        self._batch_interval = batch_interval

    async def initialize(self):
-        """Initialize the backend."""
+        """Initialize the queue and start the worker."""
+        if self._initialized:
+            return
+
+        self._queue = asyncio.Queue()
+        self._shutdown_event = asyncio.Event()
+        self._worker_task = asyncio.create_task(self._worker())
        self._initialized = True
-        logger.info("BrokerTaskBackend initialized")
+        logger.info("AsyncIOQueueBackend initialized")

    async def submit_task(self, task_dict: dict[str, Any]):
        """
-        Store task payload in async_operations table.
-
-        The task_dict should contain an 'operation_id' if updating an existing
-        operation record, otherwise a new operation will be created.
+        Submit a task by putting it in the queue.

        Args:
-            task_dict: Task dictionary to store (must be JSON serializable)
+            task_dict: Task dictionary to execute
        """
        if not self._initialized:
            await self.initialize()

-        pool = self._pool_getter()
-        operation_id = task_dict.get("operation_id")
+        await self._queue.put(task_dict)
        task_type = task_dict.get("type", "unknown")
-        bank_id = task_dict.get("bank_id")
-        payload_json = json.dumps(task_dict)
+        task_id = task_dict.get("id")

-        table = fq_table("async_operations", self._schema)
-
-        if operation_id:
-            # Update existing operation with task payload
-            await pool.execute(
-                f"""
-                UPDATE {table}
-                SET task_payload = $1::jsonb, updated_at = now()
-                WHERE operation_id = $2
-                """,
-                payload_json,
-                operation_id,
-            )
-            logger.debug(f"Updated task payload for operation {operation_id}")
-        else:
-            # Insert new operation (for tasks without pre-created records)
-            # e.g., access_count_update tasks
-            import uuid
-
-            new_id = uuid.uuid4()
-            await pool.execute(
-                f"""
-                INSERT INTO {table} (operation_id, bank_id, operation_type, status, task_payload)
-                VALUES ($1, $2, $3, 'pending', $4::jsonb)
-                """,
-                new_id,
-                bank_id,
-                task_type,
-                payload_json,
-            )
-            logger.debug(f"Created new operation {new_id} for task type {task_type}")
-
-    async def shutdown(self):
-        """Shutdown the backend."""
-        self._initialized = False
-        logger.info("BrokerTaskBackend shutdown")
-
-    async def wait_for_pending_tasks(self, timeout: float = 120.0):
+    async def wait_for_pending_tasks(self, timeout: float = 5.0):
        """
-        Wait for pending tasks to be processed.
+        Wait for all pending tasks in the queue to be processed.

-        In the broker model, this polls the database to check if tasks
-        for this process have been completed. This is useful in tests
-        when worker_enabled=True (API processes its own tasks).
+        This is useful in tests to ensure background tasks complete before assertions.

        Args:
            timeout: Maximum time to wait in seconds
        """
-        import asyncio
-
-        pool = self._pool_getter()
-        table = fq_table("async_operations", self._schema)
+        if not self._initialized or self._queue is None:
+            return

+        # Wait for queue to be empty and give worker time to process
        start_time = asyncio.get_event_loop().time()
        while asyncio.get_event_loop().time() - start_time < timeout:
-            # Check if there are any pending tasks with payloads
-            count = await pool.fetchval(
-                f"""
-                SELECT COUNT(*) FROM {table}
-                WHERE status = 'pending' AND task_payload IS NOT NULL
-                """
-            )
+            if self._queue.empty():
+                # Queue is empty, give worker a bit more time to finish any in-flight task
+                await asyncio.sleep(0.3)
+                # Check again - if still empty, we're done
+                if self._queue.empty():
+                    return
+            else:
+                # Queue not empty, wait a bit
+                await asyncio.sleep(0.1)

-            if count == 0:
-                return
+    async def shutdown(self):
+        """Shutdown the worker and drain the queue."""
+        if not self._initialized:
+            return

-            await asyncio.sleep(0.5)
+        logger.info("Shutting down AsyncIOQueueBackend...")

-        logger.warning(f"Timeout waiting for pending tasks after {timeout}s")
+        # Signal shutdown
+        self._shutdown_event.set()
+
+        # Cancel worker
+        if self._worker_task is not None:
+            self._worker_task.cancel()
+            try:
+                await self._worker_task
+            except asyncio.CancelledError:
+                pass  # Worker cancelled successfully
+
+        self._initialized = False
+        logger.info("AsyncIOQueueBackend shutdown complete")
+
+    async def _worker(self):
+        """
+        Background worker that processes tasks in batches.
+
+        Collects tasks for up to batch_interval seconds or batch_size items,
+        then processes them.
+        """
+        while not self._shutdown_event.is_set():
+            try:
+                # Collect tasks for batching
+                tasks = []
+                deadline = asyncio.get_event_loop().time() + self._batch_interval
+
+                while len(tasks) < self._batch_size and asyncio.get_event_loop().time() < deadline:
+                    try:
+                        remaining_time = max(0.1, deadline - asyncio.get_event_loop().time())
+                        task_dict = await asyncio.wait_for(self._queue.get(), timeout=remaining_time)
+                        tasks.append(task_dict)
+                    except TimeoutError:
+                        break
+
+                # Process batch
+                if tasks:
+                    # Execute tasks concurrently
+                    await asyncio.gather(
+                        *[self._execute_task(task_dict) for task_dict in tasks], return_exceptions=True
+                    )
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Worker error: {e}")
+                await asyncio.sleep(1)  # Backoff on error
@@ -49,7 +49,7 @@ async def extract_facts(
    if not text or not text.strip():
        return [], []

-    facts, chunks, _ = await extract_facts_from_text(
+    facts, chunks = await extract_facts_from_text(
        text,
        event_date,
        context=context,
@@ -27,8 +27,6 @@ from hindsight_api.extensions.operation_validator import (
    RecallResult,
    ReflectContext,
    ReflectResultContext,
-    RefreshMentalModelContext,
-    RefreshMentalModelResult,
    RetainContext,
    RetainResult,
    ValidationResult,
@@ -56,8 +54,6 @@ __all__ = [
    "RecallResult",
    "ReflectContext",
    "ReflectResultContext",
-    "RefreshMentalModelContext",
-    "RefreshMentalModelResult",
    "RetainContext",
    "RetainResult",
    "ValidationResult",
@@ -96,7 +96,7 @@ class DefaultExtensionContext(ExtensionContext):

    async def run_migration(self, schema: str) -> None:
        """Run migrations for a specific schema."""
-        from hindsight_api.migrations import ensure_embedding_dimension, run_migrations
+        from hindsight_api.migrations import run_migrations

        # Prefer getting URL from memory engine (handles pg0 case where URL is set after init)
        db_url = self._database_url
@@ -107,15 +107,6 @@ class DefaultExtensionContext(ExtensionContext):

        run_migrations(db_url, schema=schema)

-        # Ensure embedding column dimension matches the model's dimension
-        # This is needed because migrations create columns with default dimension
-        if self._memory_engine is not None:
-            embeddings = getattr(self._memory_engine, "embeddings", None)
-            if embeddings is not None:
-                dimension = getattr(embeddings, "dimension", None)
-                if dimension is not None:
-                    ensure_embedding_dimension(db_url, dimension, schema=schema)
-
    def get_memory_engine(self) -> "MemoryEngineInterface":
        """Get the memory engine interface."""
        if self._memory_engine is None:
@@ -97,18 +97,6 @@ class ReflectContext:
    context: str | None = None


-@dataclass
-class RefreshMentalModelContext:
-    """Context for a refresh mental model operation validation (pre-operation).
-
-    Contains ALL user-provided parameters for the refresh mental model operation.
-    """
-
-    bank_id: str
-    model_id: str
-    request_context: "RequestContext"
-
-
 # =============================================================================
 # Post-operation Contexts (includes results)
 # =============================================================================
@@ -176,27 +164,6 @@ class ReflectResultContext:
    error: str | None = None


-@dataclass
-class RefreshMentalModelResult:
-    """Result context for post-refresh-mental-model hook.
-
-    Contains the operation parameters and the result including token usage.
-    """
-
-    bank_id: str
-    model_id: str
-    request_context: "RequestContext"
-    # Result
-    model_name: str | None = None
-    observations_count: int = 0
-    input_tokens: int = 0
-    output_tokens: int = 0
-    total_tokens: int = 0
-    duration_ms: int = 0
-    success: bool = True
-    error: str | None = None
-
-
 class OperationValidatorExtension(Extension, ABC):
    """
    Validates and hooks into retain/recall/reflect operations.
@@ -298,25 +265,6 @@ class OperationValidatorExtension(Extension, ABC):
        """
        ...

-    @abstractmethod
-    async def validate_refresh_mental_model(self, ctx: RefreshMentalModelContext) -> ValidationResult:
-        """
-        Validate a refresh mental model operation before execution.
-
-        Called before the refresh mental model operation is processed.
-        Return ValidationResult.reject() to prevent the operation from executing.
-
-        Args:
-            ctx: Context containing all user-provided parameters:
-                - bank_id: Bank identifier
-                - model_id: Mental model ID to refresh
-                - request_context: Request context with auth info
-
-        Returns:
-            ValidationResult indicating whether the operation is allowed.
-        """
-        ...
-
    # =========================================================================
    # Post-operation hooks (optional - override to implement)
    # =========================================================================
@@ -377,28 +325,3 @@ class OperationValidatorExtension(Extension, ABC):
                - error: Error message (if failed)
        """
        pass
-
-    async def on_refresh_mental_model_complete(self, result: RefreshMentalModelResult) -> None:
-        """
-        Called after a refresh mental model operation completes (success or failure).
-
-        Override this method to implement post-operation logic such as:
-        - Token usage tracking and billing
-        - Audit logging
-        - Metrics collection
-
-        Args:
-            result: Result context containing:
-                - bank_id: Bank identifier
-                - model_id: Mental model ID
-                - request_context: Request context with auth info
-                - model_name: Name of the mental model (if success)
-                - observations_count: Number of observations generated
-                - input_tokens: Number of input tokens used
-                - output_tokens: Number of output tokens used
-                - total_tokens: Total tokens used (input + output)
-                - duration_ms: Total operation duration in milliseconds
-                - success: Whether the operation succeeded
-                - error: Error message (if failed)
-        """
-        pass
@@ -23,7 +23,7 @@ import uvicorn
 from . import MemoryEngine
 from .api import create_app
 from .banner import print_banner
-from .config import DEFAULT_WORKERS, ENV_WORKERS, HindsightConfig, get_config
+from .config import HindsightConfig, get_config
 from .daemon import (
    DEFAULT_DAEMON_PORT,
    DEFAULT_IDLE_TIMEOUT,
@@ -95,12 +95,7 @@ def main():

    # Development options
    parser.add_argument("--reload", action="store_true", help="Enable auto-reload on code changes (development only)")
-    parser.add_argument(
-        "--workers",
-        type=int,
-        default=int(os.getenv(ENV_WORKERS, str(DEFAULT_WORKERS))),
-        help=f"Number of worker processes (env: {ENV_WORKERS}, default: {DEFAULT_WORKERS})",
-    )
+    parser.add_argument("--workers", type=int, default=1, help="Number of worker processes (default: 1)")

    # Access log options
    parser.add_argument("--access-log", action="store_true", help="Enable access log")
@@ -176,57 +171,21 @@ def main():
            llm_base_url=config.llm_base_url,
            llm_max_concurrent=config.llm_max_concurrent,
            llm_timeout=config.llm_timeout,
-            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,
-            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,
            embeddings_provider=config.embeddings_provider,
            embeddings_local_model=config.embeddings_local_model,
            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_tei_url=config.reranker_tei_url,
-            reranker_tei_batch_size=config.reranker_tei_batch_size,
-            reranker_tei_max_concurrent=config.reranker_tei_max_concurrent,
-            reranker_max_candidates=config.reranker_max_candidates,
-            reranker_cohere_base_url=config.reranker_cohere_base_url,
            host=args.host,
            port=args.port,
            log_level=args.log_level,
-            log_format=config.log_format,
            mcp_enabled=config.mcp_enabled,
            graph_retriever=config.graph_retriever,
-            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_observations_async=config.retain_observations_async,
            skip_llm_verification=config.skip_llm_verification,
            lazy_reranker=config.lazy_reranker,
-            run_migrations_on_startup=config.run_migrations_on_startup,
-            db_pool_min_size=config.db_pool_min_size,
-            db_pool_max_size=config.db_pool_max_size,
-            db_command_timeout=config.db_command_timeout,
-            db_acquire_timeout=config.db_acquire_timeout,
-            worker_enabled=config.worker_enabled,
-            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,
-            reflect_max_iterations=config.reflect_max_iterations,
-            mental_model_refresh_concurrency=config.mental_model_refresh_concurrency,
        )
    config.configure_logging()
    if not args.daemon:
@@ -252,11 +211,7 @@ def main():
        logging.info(f"Loaded tenant extension: {tenant_extension.__class__.__name__}")

    # Create MemoryEngine (reads configuration from environment)
-    _memory = MemoryEngine(
-        operation_validator=operation_validator,
-        tenant_extension=tenant_extension,
-        run_migrations=config.run_migrations_on_startup,
-    )
+    _memory = MemoryEngine(operation_validator=operation_validator, tenant_extension=tenant_extension)

    # Set extension context on tenant extension (needed for schema provisioning)
    if tenant_extension:
@@ -283,27 +238,14 @@ def main():
        app = idle_middleware

    # Prepare uvicorn config
-    # When using workers or reload, we must use import string so each worker can import the app
-    use_import_string = args.workers > 1 or args.reload
-    # Check for uvloop availability
-    try:
-        import uvloop  # noqa: F401
-
-        loop_impl = "uvloop"
-        print("uvloop available, will use for event loop")
-    except ImportError:
-        loop_impl = "asyncio"
-        print("uvloop not installed, using default asyncio event loop")
-
    uvicorn_config = {
-        "app": "hindsight_api.server:app" if use_import_string else app,
+        "app": app,
        "host": args.host,
        "port": args.port,
        "log_level": args.log_level,
        "access_log": args.access_log,
        "proxy_headers": args.proxy_headers,
        "ws": "wsproto",  # Use wsproto instead of websockets to avoid deprecation warnings
-        "loop": loop_impl,  # Explicitly set event loop implementation
    }

    # Add optional parameters if provided
@@ -5,86 +5,17 @@ This module provides metrics for:
 - Operation latency (retain, recall, reflect) with percentiles
 - Token usage (input/output) per operation
 - Per-bank granularity via labels
- LLM call latency and token usage with scope dimension
- HTTP request metrics (latency, count by endpoint/method/status)
- Process metrics (CPU, memory, file descriptors, threads)
- Database connection pool metrics
 """

 import logging
-import os
-import resource
-import threading
 import time
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Callable

 from opentelemetry import metrics
 from opentelemetry.exporter.prometheus import PrometheusMetricReader
 from opentelemetry.sdk.metrics import MeterProvider
-from opentelemetry.sdk.metrics.view import ExplicitBucketHistogramAggregation, View
 from opentelemetry.sdk.resources import Resource

-if TYPE_CHECKING:
-    import asyncpg
-
-
-def _get_tenant() -> str:
-    """Get current tenant (schema) from context for metrics labeling."""
-    # Import here to avoid circular imports
-    from hindsight_api.engine.memory_engine import get_current_schema
-
-    return get_current_schema()
-
-
-# Custom bucket boundaries for operation duration (in seconds)
-# Fine granularity in 0-30s range where most operations complete
-DURATION_BUCKETS = (0.1, 0.25, 0.5, 0.75, 1.0, 2.0, 3.0, 5.0, 7.5, 10.0, 15.0, 20.0, 30.0, 60.0, 120.0)
-
-# LLM duration buckets (finer granularity for faster LLM calls)
-LLM_DURATION_BUCKETS = (0.1, 0.25, 0.5, 1.0, 2.0, 3.0, 5.0, 10.0, 15.0, 30.0, 60.0, 120.0)
-
-# HTTP request duration buckets (millisecond-level for fast endpoints)
-HTTP_DURATION_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0)
-
-
-def get_token_bucket(token_count: int) -> str:
-    """
-    Convert a token count to a bucket label for use as a dimension.
-
-    This allows analyzing token usage patterns without high-cardinality issues.
-
-    Buckets:
-    - "0-100": Very small requests/responses
-    - "100-500": Small requests/responses
-    - "500-1k": Medium requests/responses
-    - "1k-5k": Large requests/responses
-    - "5k-10k": Very large requests/responses
-    - "10k-50k": Huge requests/responses
-    - "50k+": Extremely large requests/responses
-
-    Args:
-        token_count: Number of tokens
-
-    Returns:
-        Bucket label string
-    """
-    if token_count < 100:
-        return "0-100"
-    elif token_count < 500:
-        return "100-500"
-    elif token_count < 1000:
-        return "500-1k"
-    elif token_count < 5000:
-        return "1k-5k"
-    elif token_count < 10000:
-        return "5k-10k"
-    elif token_count < 50000:
-        return "10k-50k"
-    else:
-        return "50k+"
-
-
 logger = logging.getLogger(__name__)

 # Global meter instance
@@ -117,30 +48,8 @@ def initialize_metrics(service_name: str = "hindsight-api", service_version: str
    # Create Prometheus metric reader
    prometheus_reader = PrometheusMetricReader()

-    # Create view with custom bucket boundaries for duration histogram
-    duration_view = View(
-        instrument_name="hindsight.operation.duration",
-        aggregation=ExplicitBucketHistogramAggregation(boundaries=DURATION_BUCKETS),
-    )
-
-    # Create view with custom bucket boundaries for LLM duration histogram
-    llm_duration_view = View(
-        instrument_name="hindsight.llm.duration",
-        aggregation=ExplicitBucketHistogramAggregation(boundaries=LLM_DURATION_BUCKETS),
-    )
-
-    # Create view with custom bucket boundaries for HTTP request duration histogram
-    http_duration_view = View(
-        instrument_name="hindsight.http.duration",
-        aggregation=ExplicitBucketHistogramAggregation(boundaries=HTTP_DURATION_BUCKETS),
-    )
-
-    # Create meter provider with Prometheus exporter and custom views
-    provider = MeterProvider(
-        resource=resource,
-        metric_readers=[prometheus_reader],
-        views=[duration_view, llm_duration_view, http_duration_view],
-    )
+    # Create meter provider with Prometheus exporter
+    provider = MeterProvider(resource=resource, metric_readers=[prometheus_reader])

    # Set the global meter provider
    metrics.set_meter_provider(provider)
@@ -162,84 +71,43 @@ class MetricsCollectorBase:
    """Base class for metrics collectors."""

    @contextmanager
-    def record_operation(
-        self,
-        operation: str,
-        bank_id: str,
-        source: str = "api",
-        budget: str | None = None,
-        max_tokens: int | None = None,
-    ):
+    def record_operation(self, operation: str, bank_id: str, budget: str | None = None, max_tokens: int | None = None):
        """Context manager to record operation duration and status."""
        raise NotImplementedError

-    def record_llm_call(
+    def record_tokens(
        self,
-        provider: str,
-        model: str,
-        scope: str,
-        duration: float,
+        operation: str,
+        bank_id: str,
        input_tokens: int = 0,
        output_tokens: int = 0,
-        success: bool = True,
+        budget: str | None = None,
+        max_tokens: int | None = None,
    ):
-        """
-        Record metrics for an LLM call.
-
-        Args:
-            provider: LLM provider name (openai, anthropic, gemini, groq, ollama, lmstudio)
-            model: Model name
-            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
-            success: Whether the call was successful
-        """
+        """Record token usage for an operation."""
        raise NotImplementedError

-    @contextmanager
-    def record_http_request(self, method: str, endpoint: str, status_code_getter: Callable[[], int]):
-        """Context manager to record HTTP request metrics."""
-        raise NotImplementedError
-
-    def set_db_pool(self, pool: "asyncpg.Pool"):
-        """Set the database pool for metrics collection."""
-        pass
-

 class NoOpMetricsCollector(MetricsCollectorBase):
    """No-op metrics collector that does nothing. Used when metrics are disabled."""

    @contextmanager
-    def record_operation(
-        self,
-        operation: str,
-        bank_id: str,
-        source: str = "api",
-        budget: str | None = None,
-        max_tokens: int | None = None,
-    ):
+    def record_operation(self, operation: str, bank_id: str, budget: str | None = None, max_tokens: int | None = None):
        """No-op context manager."""
        yield

-    def record_llm_call(
+    def record_tokens(
        self,
-        provider: str,
-        model: str,
-        scope: str,
-        duration: float,
+        operation: str,
+        bank_id: str,
        input_tokens: int = 0,
        output_tokens: int = 0,
-        success: bool = True,
+        budget: str | None = None,
+        max_tokens: int | None = None,
    ):
-        """No-op LLM call recording."""
+        """No-op token recording."""
        pass

-    @contextmanager
-    def record_http_request(self, method: str, endpoint: str, status_code_getter: Callable[[], int]):
-        """No-op HTTP request recording."""
-        yield
-

 class MetricsCollector(MetricsCollectorBase):
    """
@@ -257,73 +125,33 @@ class MetricsCollector(MetricsCollectorBase):
            name="hindsight.operation.duration", description="Duration of Hindsight operations in seconds", unit="s"
        )

+        # Token usage counters
+        self.tokens_input = self.meter.create_counter(
+            name="hindsight.tokens.input", description="Number of input tokens consumed", unit="tokens"
+        )
+
+        self.tokens_output = self.meter.create_counter(
+            name="hindsight.tokens.output", description="Number of output tokens generated", unit="tokens"
+        )
+
        # Operation counter (success/failure)
        self.operation_total = self.meter.create_counter(
            name="hindsight.operation.total", description="Total number of operations executed", unit="operations"
        )

-        # LLM call latency histogram (in seconds)
-        # Records duration of LLM API calls with provider, model, and scope dimensions
-        self.llm_duration = self.meter.create_histogram(
-            name="hindsight.llm.duration", description="Duration of LLM API calls in seconds", unit="s"
-        )
-
-        # LLM token usage counters with bucket labels
-        self.llm_tokens_input = self.meter.create_counter(
-            name="hindsight.llm.tokens.input", description="Number of input tokens for LLM calls", unit="tokens"
-        )
-
-        self.llm_tokens_output = self.meter.create_counter(
-            name="hindsight.llm.tokens.output", description="Number of output tokens from LLM calls", unit="tokens"
-        )
-
-        # LLM call counter (success/failure)
-        self.llm_calls_total = self.meter.create_counter(
-            name="hindsight.llm.calls.total", description="Total number of LLM API calls", unit="calls"
-        )
-
-        # HTTP request metrics
-        self.http_request_duration = self.meter.create_histogram(
-            name="hindsight.http.duration", description="Duration of HTTP requests in seconds", unit="s"
-        )
-
-        self.http_requests_total = self.meter.create_counter(
-            name="hindsight.http.requests.total", description="Total number of HTTP requests", unit="requests"
-        )
-
-        self.http_requests_in_progress = self.meter.create_up_down_counter(
-            name="hindsight.http.requests.in_progress",
-            description="Number of HTTP requests in progress",
-            unit="requests",
-        )
-
-        # Process metrics (observable gauges - collected on scrape)
-        self._setup_process_metrics()
-
-        # DB pool metrics holder (set via set_db_pool)
-        self._db_pool: "asyncpg.Pool | None" = None
-
    @contextmanager
-    def record_operation(
-        self,
-        operation: str,
-        bank_id: str,
-        source: str = "api",
-        budget: str | None = None,
-        max_tokens: int | None = None,
-    ):
+    def record_operation(self, operation: str, bank_id: str, budget: str | None = None, max_tokens: int | None = None):
        """
        Context manager to record operation duration and status.

        Usage:
-            with metrics.record_operation("recall", bank_id="user123", source="api", budget="mid", max_tokens=4096):
+            with metrics.record_operation("recall", bank_id="user123", budget="mid", max_tokens=4096):
                # ... perform operation
                pass

        Args:
-            operation: Operation name (retain, recall, reflect, entity_observation)
+            operation: Operation name (retain, recall, reflect)
            bank_id: Memory bank ID
-            source: Source of the operation (api, reflect, internal)
            budget: Optional budget level (low, mid, high)
            max_tokens: Optional max tokens for the operation
        """
@@ -331,8 +159,6 @@ class MetricsCollector(MetricsCollectorBase):
        attributes = {
            "operation": operation,
            "bank_id": bank_id,
-            "source": source,
-            "tenant": _get_tenant(),
        }
        if budget:
            attributes["budget"] = budget
@@ -355,251 +181,40 @@ class MetricsCollector(MetricsCollectorBase):
            # Record operation count
            self.operation_total.add(1, attributes)

-    def record_llm_call(
+    def record_tokens(
        self,
-        provider: str,
-        model: str,
-        scope: str,
-        duration: float,
+        operation: str,
+        bank_id: str,
        input_tokens: int = 0,
        output_tokens: int = 0,
-        success: bool = True,
+        budget: str | None = None,
+        max_tokens: int | None = None,
    ):
        """
-        Record metrics for an LLM call.
+        Record token usage for an operation.

        Args:
-            provider: LLM provider name (openai, anthropic, gemini, groq, ollama, lmstudio)
-            model: Model name
-            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
-            success: Whether the call was successful
+            operation: Operation name (retain, recall, reflect)
+            bank_id: Memory bank ID
+            input_tokens: Number of input tokens
+            output_tokens: Number of output tokens
+            budget: Optional budget level
+            max_tokens: Optional max tokens for the operation
        """
-        # Base attributes for all metrics
-        base_attributes = {
-            "provider": provider,
-            "model": model,
-            "scope": scope,
-            "success": str(success).lower(),
-            "tenant": _get_tenant(),
+        attributes = {
+            "operation": operation,
+            "bank_id": bank_id,
        }
+        if budget:
+            attributes["budget"] = budget
+        if max_tokens:
+            attributes["max_tokens"] = str(max_tokens)

-        # Record duration
-        self.llm_duration.record(duration, base_attributes)
-
-        # Record call count
-        self.llm_calls_total.add(1, base_attributes)
-
-        # Record tokens with bucket labels for cardinality control
        if input_tokens > 0:
-            input_attributes = {
-                **base_attributes,
-                "token_bucket": get_token_bucket(input_tokens),
-            }
-            self.llm_tokens_input.add(input_tokens, input_attributes)
+            self.tokens_input.add(input_tokens, attributes)

        if output_tokens > 0:
-            output_attributes = {
-                **base_attributes,
-                "token_bucket": get_token_bucket(output_tokens),
-            }
-            self.llm_tokens_output.add(output_tokens, output_attributes)
-
-    @contextmanager
-    def record_http_request(self, method: str, endpoint: str, status_code_getter: Callable[[], int]):
-        """
-        Context manager to record HTTP request metrics.
-
-        Usage:
-            status_code = [200]  # Use list for mutability
-            with metrics.record_http_request("GET", "/api/banks", lambda: status_code[0]):
-                # ... handle request
-                status_code[0] = response.status_code
-
-        Args:
-            method: HTTP method (GET, POST, etc.)
-            endpoint: Request endpoint path
-            status_code_getter: Callable that returns the status code after request completes
-        """
-        start_time = time.time()
-        base_attributes = {"method": method, "endpoint": endpoint}
-
-        # Track in-progress
-        self.http_requests_in_progress.add(1, base_attributes)
-
-        try:
-            yield
-        finally:
-            duration = time.time() - start_time
-            status_code = status_code_getter()
-            status_class = f"{status_code // 100}xx"
-
-            # Get tenant from context (may be set during request processing)
-            tenant = _get_tenant()
-
-            attributes = {
-                **base_attributes,
-                "status_code": str(status_code),
-                "status_class": status_class,
-                "tenant": tenant,
-            }
-
-            # Record duration and count
-            self.http_request_duration.record(duration, attributes)
-            self.http_requests_total.add(1, attributes)
-
-            # Decrement in-progress
-            self.http_requests_in_progress.add(-1, base_attributes)
-
-    def _setup_process_metrics(self):
-        """Set up observable gauges for process metrics."""
-
-        def get_cpu_times(_options):
-            """Get process CPU times."""
-            try:
-                rusage = resource.getrusage(resource.RUSAGE_SELF)
-                yield metrics.Observation(rusage.ru_utime, {"type": "user"})
-                yield metrics.Observation(rusage.ru_stime, {"type": "system"})
-            except Exception:
-                pass
-
-        def get_memory_usage(_options):
-            """Get process memory usage in bytes."""
-            try:
-                rusage = resource.getrusage(resource.RUSAGE_SELF)
-                # ru_maxrss is in kilobytes on Linux, bytes on macOS
-                max_rss = rusage.ru_maxrss
-                if os.uname().sysname == "Linux":
-                    max_rss *= 1024  # Convert KB to bytes
-                yield metrics.Observation(max_rss, {"type": "rss_max"})
-            except Exception:
-                pass
-
-        def get_open_file_descriptors(_options):
-            """Get number of open file descriptors."""
-            try:
-                # Try to count open FDs by checking /proc on Linux
-                if os.path.exists("/proc/self/fd"):
-                    count = len(os.listdir("/proc/self/fd"))
-                    yield metrics.Observation(count)
-                else:
-                    # Fallback: use resource limits
-                    soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
-                    yield metrics.Observation(soft, {"limit": "soft"})
-            except Exception:
-                pass
-
-        def get_thread_count(_options):
-            """Get number of active threads."""
-            try:
-                yield metrics.Observation(threading.active_count())
-            except Exception:
-                pass
-
-        # Create observable gauges
-        self.meter.create_observable_gauge(
-            name="hindsight.process.cpu.seconds",
-            callbacks=[get_cpu_times],
-            description="Process CPU time in seconds",
-            unit="s",
-        )
-
-        self.meter.create_observable_gauge(
-            name="hindsight.process.memory.bytes",
-            callbacks=[get_memory_usage],
-            description="Process memory usage in bytes",
-            unit="By",
-        )
-
-        self.meter.create_observable_gauge(
-            name="hindsight.process.open_fds",
-            callbacks=[get_open_file_descriptors],
-            description="Number of open file descriptors",
-            unit="{fds}",
-        )
-
-        self.meter.create_observable_gauge(
-            name="hindsight.process.threads",
-            callbacks=[get_thread_count],
-            description="Number of active threads",
-            unit="{threads}",
-        )
-
-    def set_db_pool(self, pool: "asyncpg.Pool"):
-        """
-        Set the database pool for metrics collection.
-
-        Args:
-            pool: asyncpg connection pool instance
-        """
-        self._db_pool = pool
-        self._setup_db_pool_metrics()
-
-    def _setup_db_pool_metrics(self):
-        """Set up observable gauges for database pool metrics."""
-
-        def get_pool_size(_options):
-            """Get current pool size."""
-            if self._db_pool is not None:
-                try:
-                    yield metrics.Observation(self._db_pool.get_size())
-                except Exception:
-                    pass
-
-        def get_pool_free_size(_options):
-            """Get number of free connections in pool."""
-            if self._db_pool is not None:
-                try:
-                    yield metrics.Observation(self._db_pool.get_idle_size())
-                except Exception:
-                    pass
-
-        def get_pool_min_size(_options):
-            """Get pool minimum size."""
-            if self._db_pool is not None:
-                try:
-                    yield metrics.Observation(self._db_pool.get_min_size())
-                except Exception:
-                    pass
-
-        def get_pool_max_size(_options):
-            """Get pool maximum size."""
-            if self._db_pool is not None:
-                try:
-                    yield metrics.Observation(self._db_pool.get_max_size())
-                except Exception:
-                    pass
-
-        # Create observable gauges for pool metrics
-        self.meter.create_observable_gauge(
-            name="hindsight.db.pool.size",
-            callbacks=[get_pool_size],
-            description="Current number of connections in the pool",
-            unit="{connections}",
-        )
-
-        self.meter.create_observable_gauge(
-            name="hindsight.db.pool.idle",
-            callbacks=[get_pool_free_size],
-            description="Number of idle connections in the pool",
-            unit="{connections}",
-        )
-
-        self.meter.create_observable_gauge(
-            name="hindsight.db.pool.min",
-            callbacks=[get_pool_min_size],
-            description="Minimum pool size",
-            unit="{connections}",
-        )
-
-        self.meter.create_observable_gauge(
-            name="hindsight.db.pool.max",
-            callbacks=[get_pool_max_size],
-            description="Maximum pool size",
-            unit="{connections}",
-        )
+            self.tokens_output.add(output_tokens, attributes)


 # Global metrics collector instance (defaults to no-op)
@@ -22,7 +22,6 @@ from pathlib import Path

 from alembic import command
 from alembic.config import Config
-from alembic.script.revision import ResolutionError
 from sqlalchemy import create_engine, text

 logger = logging.getLogger(__name__)
@@ -79,18 +78,7 @@ def _run_migrations_internal(database_url: str, script_location: str, schema: st
        alembic_cfg.set_main_option("target_schema", schema)

    # Run migrations
-    try:
-        command.upgrade(alembic_cfg, "head")
-    except ResolutionError as e:
-        # This happens during rolling deployments when a newer version of the code
-        # has already run migrations, and this older replica doesn't have the new
-        # migration files. The database is already at a newer revision than we know.
-        # This is safe to ignore - the newer code has already applied its migrations.
-        logger.warning(
-            f"Database is at a newer migration revision than this code version knows about. "
-            f"This is expected during rolling deployments. Skipping migrations. Error: {e}"
-        )
-        return
+    command.upgrade(alembic_cfg, "head")

    logger.info(f"Database migrations completed successfully for schema '{schema_name}'")

@@ -241,131 +229,3 @@ def check_migration_status(
    except Exception as e:
        logger.warning(f"Unable to check migration status: {e}")
        return None, None
-
-
-def ensure_embedding_dimension(
-    database_url: str,
-    required_dimension: int,
-    schema: str | None = None,
-) -> None:
-    """
-    Ensure the embedding column dimension matches the model's dimension.
-
-    This function checks the current vector column dimension in the database
-    and adjusts it if necessary:
-    - If dimensions match: no action needed
-    - If dimensions differ and table is empty: ALTER COLUMN to new dimension
-    - If dimensions differ and table has data: raise error with migration guidance
-
-    Args:
-        database_url: SQLAlchemy database URL
-        required_dimension: The embedding dimension required by the model
-        schema: Target PostgreSQL schema name (None for public)
-
-    Raises:
-        RuntimeError: If dimension mismatch with existing data
-    """
-    schema_name = schema or "public"
-
-    engine = create_engine(database_url)
-    with engine.connect() as conn:
-        # Check if memory_units table exists
-        table_exists = conn.execute(
-            text("""
-                SELECT EXISTS (
-                    SELECT 1 FROM information_schema.tables
-                    WHERE table_schema = :schema AND table_name = 'memory_units'
-                )
-            """),
-            {"schema": schema_name},
-        ).scalar()
-
-        if not table_exists:
-            logger.debug(f"memory_units table does not exist in schema '{schema_name}', skipping dimension check")
-            return
-
-        # Get current column dimension from pg_attribute
-        # pgvector stores dimension in atttypmod
-        current_dim = conn.execute(
-            text("""
-                SELECT atttypmod
-                FROM pg_attribute a
-                JOIN pg_class c ON a.attrelid = c.oid
-                JOIN pg_namespace n ON c.relnamespace = n.oid
-                WHERE n.nspname = :schema
-                  AND c.relname = 'memory_units'
-                  AND a.attname = 'embedding'
-            """),
-            {"schema": schema_name},
-        ).scalar()
-
-        if current_dim is None:
-            logger.warning("Could not determine current embedding dimension, skipping check")
-            return
-
-        # pgvector stores dimension directly in atttypmod (no offset like other types)
-        current_dimension = current_dim
-
-        if current_dimension == required_dimension:
-            logger.debug(f"Embedding dimension OK: {current_dimension}")
-            return
-
-        logger.info(
-            f"Embedding dimension mismatch: database has {current_dimension}, model requires {required_dimension}"
-        )
-
-        # Check if table has data
-        row_count = conn.execute(
-            text(f"SELECT COUNT(*) FROM {schema_name}.memory_units WHERE embedding IS NOT NULL")
-        ).scalar()
-
-        if row_count > 0:
-            raise RuntimeError(
-                f"Cannot change embedding dimension from {current_dimension} to {required_dimension}: "
-                f"memory_units table contains {row_count} rows with embeddings. "
-                f"To change dimensions, you must either:\n"
-                f"  1. Re-embed all data: DELETE FROM {schema_name}.memory_units; then restart\n"
-                f"  2. Use a model with {current_dimension}-dimensional embeddings"
-            )
-
-        # Table is empty, safe to alter column
-        logger.info(f"Altering embedding column dimension from {current_dimension} to {required_dimension}")
-
-        # Drop the HNSW index on embedding column if it exists
-        # Only drop indexes that use 'hnsw' and reference the 'embedding' column
-        conn.execute(
-            text(f"""
-                DO $$
-                DECLARE idx_name TEXT;
-                BEGIN
-                    FOR idx_name IN
-                        SELECT indexname FROM pg_indexes
-                        WHERE schemaname = '{schema_name}'
-                          AND tablename = 'memory_units'
-                          AND indexdef LIKE '%hnsw%'
-                          AND indexdef LIKE '%embedding%'
-                    LOOP
-                        EXECUTE 'DROP INDEX IF EXISTS {schema_name}.' || idx_name;
-                    END LOOP;
-                END $$;
-            """)
-        )
-
-        # Alter the column type
-        conn.execute(
-            text(f"ALTER TABLE {schema_name}.memory_units ALTER COLUMN embedding TYPE vector({required_dimension})")
-        )
-        conn.commit()
-
-        # Recreate the HNSW index
-        conn.execute(
-            text(f"""
-                CREATE INDEX IF NOT EXISTS idx_memory_units_embedding_hnsw
-                ON {schema_name}.memory_units
-                USING hnsw (embedding vector_cosine_ops)
-                WITH (m = 16, ef_construction = 64)
-            """)
-        )
-        conn.commit()
-
-        logger.info(f"Successfully changed embedding dimension to {required_dimension}")
@@ -41,8 +41,6 @@ from sqlalchemy.dialects.postgresql import JSONB, TIMESTAMP, UUID
 from sqlalchemy.ext.asyncio import AsyncAttrs
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship

-from .config import EMBEDDING_DIMENSION
-

 class Base(AsyncAttrs, DeclarativeBase):
    """Base class for all models."""
@@ -83,7 +81,7 @@ class MemoryUnit(Base):
    bank_id: Mapped[str] = mapped_column(Text, nullable=False)
    document_id: Mapped[str | None] = mapped_column(Text)
    text: Mapped[str] = mapped_column(Text, nullable=False)
-    embedding = mapped_column(Vector(EMBEDDING_DIMENSION))  # pgvector type
+    embedding = mapped_column(Vector(384))  # pgvector type
    context: Mapped[str | None] = mapped_column(Text)
    event_date: Mapped[datetime] = mapped_column(
        TIMESTAMP(timezone=True), nullable=False
@@ -132,56 +132,3 @@ async def stop_embedded_postgres() -> None:
    global _default_instance
    if _default_instance:
        await _default_instance.stop()
-
-
-def parse_pg0_url(db_url: str) -> tuple[bool, str | None, int | None]:
-    """
-    Parse a database URL and check if it's a pg0:// embedded database URL.
-
-    Supports:
-    - "pg0" -> default instance "hindsight"
-    - "pg0://instance-name" -> named instance
-    - "pg0://instance-name:port" -> named instance with explicit port
-    - Any other URL (e.g., postgresql://) -> not a pg0 URL
-
-    Args:
-        db_url: The database URL to parse
-
-    Returns:
-        Tuple of (is_pg0, instance_name, port)
-        - is_pg0: True if this is a pg0 URL
-        - instance_name: The instance name (or None if not pg0)
-        - port: The explicit port (or None for auto-assign)
-    """
-    if db_url == "pg0":
-        return True, "hindsight", None
-
-    if db_url.startswith("pg0://"):
-        url_part = db_url[6:]  # Remove "pg0://"
-        if ":" in url_part:
-            instance_name, port_str = url_part.rsplit(":", 1)
-            return True, instance_name or "hindsight", int(port_str)
-        else:
-            return True, url_part or "hindsight", None
-
-    return False, None, None
-
-
-async def resolve_database_url(db_url: str) -> str:
-    """
-    Resolve a database URL, handling pg0:// embedded database URLs.
-
-    If the URL is a pg0:// URL, starts the embedded PostgreSQL and returns
-    the actual postgresql:// connection URL. Otherwise, returns the URL unchanged.
-
-    Args:
-        db_url: Database URL (pg0://, pg0, or postgresql://)
-
-    Returns:
-        The resolved postgresql:// connection URL
-    """
-    is_pg0, instance_name, port = parse_pg0_url(db_url)
-    if is_pg0:
-        pg0 = EmbeddedPostgres(name=instance_name, port=port)
-        return await pg0.ensure_running()
-    return db_url
@@ -7,7 +7,6 @@ This module provides the ASGI app for uvicorn import string usage:
 For CLI usage, use the hindsight-api command instead.
 """

-import logging
 import os
 import warnings

@@ -18,12 +17,6 @@ warnings.filterwarnings("ignore", message="websockets.server.WebSocketServerProt
 from hindsight_api import MemoryEngine
 from hindsight_api.api import create_app
 from hindsight_api.config import get_config
-from hindsight_api.extensions import (
-    DefaultExtensionContext,
-    OperationValidatorExtension,
-    TenantExtension,
-    load_extension,
-)

 # Disable tokenizers parallelism to avoid warnings
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
@@ -32,42 +25,12 @@ os.environ["TOKENIZERS_PARALLELISM"] = "false"
 config = get_config()
 config.configure_logging()

-# Load operation validator extension if configured
-operation_validator = load_extension("OPERATION_VALIDATOR", OperationValidatorExtension)
-if operation_validator:
-    logging.info(f"Loaded operation validator: {operation_validator.__class__.__name__}")
-
-# Load tenant extension if configured
-tenant_extension = load_extension("TENANT", TenantExtension)
-if tenant_extension:
-    logging.info(f"Loaded tenant extension: {tenant_extension.__class__.__name__}")
-
 # Create app at module level (required for uvicorn import string)
 # MemoryEngine reads configuration from environment variables automatically
-# Note: run_migrations=True by default, but migrations are idempotent so safe with workers
-_memory = MemoryEngine(
-    operation_validator=operation_validator,
-    tenant_extension=tenant_extension,
-    run_migrations=config.run_migrations_on_startup,
-)
-
-# Set extension context on tenant extension (needed for schema provisioning)
-if tenant_extension:
-    extension_context = DefaultExtensionContext(
-        database_url=config.database_url,
-        memory_engine=_memory,
-    )
-    tenant_extension.set_context(extension_context)
-    logging.info("Extension context set on tenant extension")
+_memory = MemoryEngine()

 # Create unified app with both HTTP and optionally MCP
-app = create_app(
-    memory=_memory,
-    http_api_enabled=True,
-    mcp_api_enabled=config.mcp_enabled,
-    mcp_mount_path="/mcp",
-    initialize_memory=True,
-)
+app = create_app(memory=_memory, http_api_enabled=True, mcp_api_enabled=config.mcp_enabled, mcp_mount_path="/mcp")


 if __name__ == "__main__":
@@ -1,11 +0,0 @@
-"""
-Worker package for distributed task processing.
-
-This package provides:
- WorkerPoller: Polls PostgreSQL for pending tasks and executes them
- main: CLI entry point for hindsight-worker
-"""
-
-from .poller import WorkerPoller
-
-__all__ = ["WorkerPoller"]
@@ -1,285 +0,0 @@
-"""
-Command-line interface for Hindsight Worker.
-
-Run the worker with:
-    hindsight-worker
-
-Stop with Ctrl+C (graceful shutdown).
-"""
-
-import argparse
-import asyncio
-import atexit
-import logging
-import os
-import signal
-import socket
-import sys
-import warnings
-
-from ..config import get_config
-from ..engine.task_backend import SyncTaskBackend
-from .poller import WorkerPoller
-
-# Filter deprecation warnings from third-party libraries
-warnings.filterwarnings("ignore", message="websockets.legacy is deprecated")
-warnings.filterwarnings("ignore", message="websockets.server.WebSocketServerProtocol is deprecated")
-
-# Disable tokenizers parallelism to avoid warnings
-os.environ["TOKENIZERS_PARALLELISM"] = "false"
-
-logger = logging.getLogger(__name__)
-
-
-def create_worker_app(poller: WorkerPoller, memory):
-    """Create a minimal FastAPI app for worker metrics and health."""
-    from fastapi import FastAPI
-    from fastapi.responses import JSONResponse, Response
-    from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
-
-    from ..metrics import create_metrics_collector, get_metrics_collector, initialize_metrics
-
-    app = FastAPI(
-        title="Hindsight Worker",
-        description="Worker process for distributed task execution",
-    )
-
-    # Initialize OpenTelemetry metrics
-    try:
-        prometheus_reader = initialize_metrics(service_name="hindsight-worker", service_version="1.0.0")
-        create_metrics_collector()
-        app.state.prometheus_reader = prometheus_reader
-        logger.info("Metrics initialized - available at /metrics endpoint")
-    except Exception as e:
-        logger.warning(f"Failed to initialize metrics: {e}. Metrics will be disabled.")
-        app.state.prometheus_reader = None
-
-    # Set up DB pool metrics if available
-    metrics_collector = get_metrics_collector()
-    if memory._pool is not None and hasattr(metrics_collector, "set_db_pool"):
-        metrics_collector.set_db_pool(memory._pool)
-        logger.info("DB pool metrics configured")
-
-    @app.get(
-        "/health",
-        summary="Health check endpoint",
-        description="Returns worker health status including database connectivity",
-        tags=["Monitoring"],
-    )
-    async def health_endpoint():
-        """Health check endpoint."""
-        health = await memory.health_check()
-        health["worker_id"] = poller.worker_id
-        health["is_shutdown"] = poller.is_shutdown
-        status_code = 200 if health.get("status") == "healthy" else 503
-        return JSONResponse(content=health, status_code=status_code)
-
-    @app.get(
-        "/metrics",
-        summary="Prometheus metrics endpoint",
-        description="Exports metrics in Prometheus format for scraping",
-        tags=["Monitoring"],
-    )
-    async def metrics_endpoint():
-        """Return Prometheus metrics."""
-        metrics_data = generate_latest()
-        return Response(content=metrics_data, media_type=CONTENT_TYPE_LATEST)
-
-    @app.get(
-        "/",
-        summary="Worker info",
-        description="Basic worker information",
-        tags=["Info"],
-    )
-    async def root():
-        """Return basic worker info."""
-        return {
-            "service": "hindsight-worker",
-            "worker_id": poller.worker_id,
-            "is_shutdown": poller.is_shutdown,
-        }
-
-    return app
-
-
-def main():
-    """Main entry point for the hindsight-worker CLI."""
-    # Load configuration from environment
-    config = get_config()
-
-    parser = argparse.ArgumentParser(
-        prog="hindsight-worker",
-        description="Hindsight Worker - distributed task processor",
-    )
-
-    # Worker options
-    parser.add_argument(
-        "--worker-id",
-        default=config.worker_id or socket.gethostname(),
-        help="Worker identifier (default: hostname, env: HINDSIGHT_API_WORKER_ID)",
-    )
-    parser.add_argument(
-        "--poll-interval",
-        type=int,
-        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,
-        default=config.worker_max_retries,
-        help=f"Max retries before marking failed (default: {config.worker_max_retries}, env: HINDSIGHT_API_WORKER_MAX_RETRIES)",
-    )
-
-    # HTTP server options
-    parser.add_argument(
-        "--http-port",
-        type=int,
-        default=config.worker_http_port,
-        help=f"HTTP port for metrics/health endpoints (default: {config.worker_http_port}, env: HINDSIGHT_API_WORKER_HTTP_PORT)",
-    )
-    parser.add_argument(
-        "--http-host",
-        default="0.0.0.0",
-        help="HTTP host to bind (default: 0.0.0.0)",
-    )
-
-    # Logging options
-    parser.add_argument(
-        "--log-level",
-        default=config.log_level,
-        choices=["critical", "error", "warning", "info", "debug", "trace"],
-        help=f"Log level (default: {config.log_level}, env: HINDSIGHT_API_LOG_LEVEL)",
-    )
-
-    args = parser.parse_args()
-
-    # Configure logging
-    config.configure_logging()
-
-    # Import MemoryEngine here to avoid circular imports
-    from .. import MemoryEngine
-
-    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"  HTTP server: {args.http_host}:{args.http_port}")
-    print()
-
-    # Global references for cleanup
-    memory = None
-    poller = None
-
-    async def run():
-        nonlocal memory, poller
-        import uvicorn
-
-        # Initialize MemoryEngine
-        # Workers use SyncTaskBackend because they execute tasks directly,
-        # they don't need to store tasks (they poll from DB)
-        memory = MemoryEngine(
-            run_migrations=False,  # Workers don't run migrations
-            task_backend=SyncTaskBackend(),
-        )
-
-        await memory.initialize()
-
-        print(f"Database connected: {config.database_url}")
-
-        # Create and start the poller
-        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,
-        )
-
-        # Create the HTTP app for metrics/health
-        app = create_worker_app(poller, memory)
-
-        # Setup signal handlers for graceful shutdown
-        shutdown_requested = asyncio.Event()
-
-        def signal_handler(signum, frame):
-            print(f"\nReceived signal {signum}, initiating graceful shutdown...")
-            shutdown_requested.set()
-
-        signal.signal(signal.SIGINT, signal_handler)
-        signal.signal(signal.SIGTERM, signal_handler)
-
-        # Create uvicorn config and server
-        uvicorn_config = uvicorn.Config(
-            app,
-            host=args.http_host,
-            port=args.http_port,
-            log_level="info",  # Reduce uvicorn noise
-            access_log=False,
-        )
-        server = uvicorn.Server(uvicorn_config)
-
-        # Run the poller and HTTP server concurrently
-        poller_task = asyncio.create_task(poller.run())
-        http_task = asyncio.create_task(server.serve())
-
-        print(f"Worker started. Metrics available at http://{args.http_host}:{args.http_port}/metrics")
-
-        # Wait for shutdown signal
-        await shutdown_requested.wait()
-
-        # Graceful shutdown
-        print("Shutting down HTTP server...")
-        server.should_exit = True
-
-        print("Waiting for poller to finish...")
-        await poller.shutdown_graceful(timeout=30.0)
-        poller_task.cancel()
-        try:
-            await poller_task
-        except asyncio.CancelledError:
-            pass
-
-        # Wait for HTTP server to finish
-        try:
-            await asyncio.wait_for(http_task, timeout=5.0)
-        except asyncio.TimeoutError:
-            http_task.cancel()
-            try:
-                await http_task
-            except asyncio.CancelledError:
-                pass
-
-        # Close memory engine
-        await memory.close()
-        print("Worker shutdown complete")
-
-    def cleanup():
-        """Synchronous cleanup for atexit."""
-        if memory is not None and memory._pg0 is not None:
-            try:
-                loop = asyncio.new_event_loop()
-                loop.run_until_complete(memory._pg0.stop())
-                loop.close()
-                print("\npg0 stopped.")
-            except Exception as e:
-                print(f"\nError stopping pg0: {e}")
-
-    atexit.register(cleanup)
-
-    try:
-        asyncio.run(run())
-    except KeyboardInterrupt:
-        print("\nWorker interrupted")
-        sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()
@@ -1,281 +0,0 @@
-"""
-Worker poller for distributed task execution.
-
-Polls PostgreSQL for pending tasks and executes them using
-FOR UPDATE SKIP LOCKED for safe concurrent claiming.
-"""
-
-import asyncio
-import json
-import logging
-import traceback
-from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    import asyncpg
-
-logger = logging.getLogger(__name__)
-
-
-def fq_table(table: str, schema: str | None = None) -> str:
-    """Get fully-qualified table name with optional schema prefix."""
-    if schema:
-        return f'"{schema}".{table}'
-    return table
-
-
-class WorkerPoller:
-    """
-    Polls PostgreSQL for pending tasks and executes them.
-
-    Uses FOR UPDATE SKIP LOCKED for safe distributed claiming,
-    allowing multiple workers to process tasks without conflicts.
-    """
-
-    def __init__(
-        self,
-        pool: "asyncpg.Pool",
-        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,
-    ):
-        """
-        Initialize the worker poller.
-
-        Args:
-            pool: asyncpg connection pool
-            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 multi-tenant support (optional)
-        """
-        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
-        self._shutdown = asyncio.Event()
-        self._current_tasks: set[asyncio.Task] = set()
-        self._in_flight_count = 0
-        self._in_flight_lock = asyncio.Lock()
-
-    async def claim_batch(self) -> list[tuple[str, dict[str, Any]]]:
-        """
-        Claim up to batch_size pending tasks atomically.
-
-        Uses FOR UPDATE SKIP LOCKED to ensure no conflicts with other workers.
-
-        Returns:
-            List of tuples (operation_id, task_dict)
-        """
-        table = fq_table("async_operations", self._schema)
-
-        async with self._pool.acquire() as conn:
-            async with conn.transaction():
-                # Select and lock pending tasks
-                rows = await conn.fetch(
-                    f"""
-                    SELECT operation_id, task_payload
-                    FROM {table}
-                    WHERE status = 'pending' AND task_payload IS NOT NULL
-                    ORDER BY created_at
-                    LIMIT $1
-                    FOR UPDATE SKIP LOCKED
-                    """,
-                    self._batch_size,
-                )
-
-                if not rows:
-                    return []
-
-                # Claim the tasks by updating status and worker_id
-                operation_ids = [row["operation_id"] for row in rows]
-                await conn.execute(
-                    f"""
-                    UPDATE {table}
-                    SET status = 'processing', worker_id = $1, claimed_at = now(), updated_at = now()
-                    WHERE operation_id = ANY($2)
-                    """,
-                    self._worker_id,
-                    operation_ids,
-                )
-
-                # Parse and return task payloads
-                return [(str(row["operation_id"]), json.loads(row["task_payload"])) for row in rows]
-
-    async def _mark_completed(self, operation_id: str):
-        """Mark a task as completed."""
-        table = fq_table("async_operations", self._schema)
-        await self._pool.execute(
-            f"""
-            UPDATE {table}
-            SET status = 'completed', completed_at = now(), updated_at = now()
-            WHERE operation_id = $1
-            """,
-            operation_id,
-        )
-
-    async def _mark_failed(self, operation_id: str, error_message: str):
-        """Mark a task as failed with error message."""
-        table = fq_table("async_operations", self._schema)
-        # Truncate error message if too long (max 5000 chars in schema)
-        error_message = error_message[:5000] if len(error_message) > 5000 else error_message
-        await self._pool.execute(
-            f"""
-            UPDATE {table}
-            SET status = 'failed', error_message = $2, completed_at = now(), updated_at = now()
-            WHERE operation_id = $1
-            """,
-            operation_id,
-            error_message,
-        )
-
-    async def _retry_or_fail(self, operation_id: str, error_message: str):
-        """Increment retry count or mark as failed if max retries exceeded."""
-        table = fq_table("async_operations", self._schema)
-
-        # Get current retry count
-        row = await self._pool.fetchrow(
-            f"SELECT retry_count FROM {table} WHERE operation_id = $1",
-            operation_id,
-        )
-
-        if row is None:
-            logger.warning(f"Operation {operation_id} not found, cannot retry")
-            return
-
-        retry_count = row["retry_count"]
-
-        if retry_count >= self._max_retries:
-            # Max retries exceeded, mark as failed
-            await self._mark_failed(
-                operation_id, f"Max retries ({self._max_retries}) exceeded. Last error: {error_message}"
-            )
-            logger.error(f"Task {operation_id} failed after {retry_count} retries")
-        else:
-            # Increment retry and reset to pending
-            await self._pool.execute(
-                f"""
-                UPDATE {table}
-                SET status = 'pending', worker_id = NULL, claimed_at = NULL,
-                    retry_count = retry_count + 1, updated_at = now()
-                WHERE operation_id = $1
-                """,
-                operation_id,
-            )
-            logger.warning(f"Task {operation_id} failed, will retry (attempt {retry_count + 1}/{self._max_retries})")
-
-    async def execute_task(self, operation_id: str, task_dict: dict[str, Any]):
-        """Execute a single task and update its status."""
-        task_type = task_dict.get("type", "unknown")
-        bank_id = task_dict.get("bank_id", "unknown")
-
-        try:
-            logger.debug(f"Executing task {operation_id} (type={task_type}, bank={bank_id})")
-            await self._executor(task_dict)
-            await self._mark_completed(operation_id)
-            logger.debug(f"Task {operation_id} completed successfully")
-        except Exception as e:
-            error_msg = f"{type(e).__name__}: {e}\n{traceback.format_exc()}"
-            logger.error(f"Task {operation_id} failed: {e}")
-            await self._retry_or_fail(operation_id, error_msg)
-
-    async def run(self):
-        """
-        Main polling loop.
-
-        Continuously polls for pending tasks, claims them, and executes them
-        until shutdown is signaled.
-        """
-        logger.info(f"Worker {self._worker_id} starting polling loop")
-
-        while not self._shutdown.is_set():
-            try:
-                # Claim a batch of tasks
-                tasks = await self.claim_batch()
-
-                if tasks:
-                    # Log batch info
-                    task_types = {}
-                    for _, task_dict in tasks:
-                        t = task_dict.get("type", "unknown")
-                        task_types[t] = task_types.get(t, 0) + 1
-                    types_str = ", ".join(f"{k}:{v}" for k, v in task_types.items())
-                    logger.info(f"Worker {self._worker_id} claimed {len(tasks)} tasks: {types_str}")
-
-                    # Track in-flight tasks
-                    async with self._in_flight_lock:
-                        self._in_flight_count += len(tasks)
-
-                    # Execute tasks concurrently
-                    try:
-                        await asyncio.gather(
-                            *[self.execute_task(op_id, task_dict) for op_id, task_dict 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
-
-            except asyncio.CancelledError:
-                logger.info(f"Worker {self._worker_id} polling loop cancelled")
-                break
-            except Exception as e:
-                logger.error(f"Worker {self._worker_id} error in polling loop: {e}")
-                traceback.print_exc()
-                # Backoff on error
-                await asyncio.sleep(1)
-
-        logger.info(f"Worker {self._worker_id} polling loop stopped")
-
-    async def shutdown_graceful(self, timeout: float = 30.0):
-        """
-        Signal shutdown and wait for current tasks to complete.
-
-        Args:
-            timeout: Maximum time to wait for in-flight tasks (seconds)
-        """
-        logger.info(f"Worker {self._worker_id} initiating graceful shutdown")
-        self._shutdown.set()
-
-        # Wait for in-flight tasks to complete
-        start_time = asyncio.get_event_loop().time()
-        while asyncio.get_event_loop().time() - start_time < timeout:
-            async with self._in_flight_lock:
-                in_flight = self._in_flight_count
-
-            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)
-
-        logger.warning(f"Worker {self._worker_id} shutdown timeout after {timeout}s")
-
-    @property
-    def worker_id(self) -> str:
-        """Get the worker ID."""
-        return self._worker_id
-
-    @property
-    def is_shutdown(self) -> bool:
-        """Check if shutdown has been signaled."""
-        return self._shutdown.is_set()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-api"
-version = "0.3.0"
+version = "0.1.16"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,6 +14,7 @@ dependencies = [
    "openai>=1.0.0",
    "pydantic>=2.0.0",
    "rich>=13.0.0",
+    "sentence-transformers>=3.0.0,<3.3.0",
    "langchain-text-splitters>=0.3.0",
    "fastapi[standard]>=0.120.3",
    "uvicorn>=0.38.0",
@@ -23,9 +24,11 @@ dependencies = [
    "pgvector>=0.4.1",
    "greenlet>=3.2.4",
    "psycopg2-binary>=2.9.11",
+    "transformers>=4.30.0,<4.46.0",
+    "torch>=2.0.0",
    "tiktoken>=0.12.0",
    "httpx>=0.27.0",
-    "fastmcp>=2.14.0",  # CVE-2025-66416
+    "fastmcp>=2.3.0",
    "pg0-embedded>=0.11.0",
    "python-dateutil>=2.8.0",
    "opentelemetry-api>=1.20.0",
@@ -35,21 +38,6 @@ dependencies = [
    "dateparser>=1.2.2",
    "google-genai>=1.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
-    "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
 ]

 [project.optional-dependencies]
@@ -58,14 +46,12 @@ test = [
    "pytest-asyncio>=0.21.0",
    "pytest-timeout>=2.4.0",
    "pytest-xdist>=3.0.0",
-    "filelock>=3.20.1",  # TOCTOU race condition fix
+    "filelock>=3.0.0",
 ]

 [project.scripts]
 hindsight-api = "hindsight_api.main:main"
-hindsight-worker = "hindsight_api.worker.main:main"
 hindsight-local-mcp = "hindsight_api.mcp_local:main"
-hindsight-admin = "hindsight_api.admin.cli:main"

 [tool.hatch.build.targets.wheel]
 packages = ["hindsight_api"]
@@ -89,7 +75,7 @@ log_cli = true
 log_cli_level = "INFO"
 log_cli_format = "%(asctime)s - %(levelname)s - %(name)s - %(message)s"
 log_cli_date_format = "%Y-%m-%d %H:%M:%S"
-addopts = "--timeout 120 -n 8 --dist loadgroup --durations=10 -v"
+addopts = "--timeout 120 -n 8 --durations=10 -v"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 log_auto_indent = true
@@ -105,7 +91,7 @@ dev = [
    "pytest-timeout>=2.4.0",
    "pytest-xdist>=3.8.0",
    "python-dotenv>=1.2.1",
-    "filelock>=3.20.1",  # TOCTOU race condition fix
+    "filelock>=3.0.0",
    "ruff>=0.8.0",
    "ty>=0.0.1",
 ]
@@ -134,9 +120,6 @@ ignore = [
    "F821",   # undefined name (forward references in type hints)
 ]

-[tool.ruff.lint.isort]
-known-third-party = ["alembic"]
-
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
@@ -12,7 +12,6 @@ from hindsight_api import MemoryEngine, LLMConfig, LocalSTEmbeddings, RequestCon

 from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder
 from hindsight_api.engine.query_analyzer import DateparserQueryAnalyzer
-from hindsight_api.engine.task_backend import SyncTaskBackend
 from hindsight_api.pg0 import EmbeddedPostgres

 # Default pg0 instance configuration for tests
@@ -148,7 +147,6 @@ async def memory(pg0_db_url, embeddings, cross_encoder, query_analyzer):
    Uses pg0_db_url (a postgresql:// URL) directly, so MemoryEngine won't try to
    manage pg0 lifecycle - that's handled by the session-scoped pg0_db_url fixture.
    Migrations are disabled here since they're run once at session scope in pg0_db_url.
-    Uses SyncTaskBackend so async tasks execute immediately (no worker needed).
    """
    mem = MemoryEngine(
        db_url=pg0_db_url,  # Direct postgresql:// URL, not pg0://
@@ -162,7 +160,6 @@ async def memory(pg0_db_url, embeddings, cross_encoder, query_analyzer):
        pool_min_size=1,
        pool_max_size=5,
        run_migrations=False,  # Migrations already run at session scope
-        task_backend=SyncTaskBackend(),  # Execute tasks immediately in tests
    )
    await mem.initialize()
    yield mem
@@ -1,292 +0,0 @@
-"""
-Tests for admin backup and restore functionality.
-
-These tests use an isolated schema to avoid interfering with other tests.
-The backup/restore operations truncate tables, which would cause deadlocks
-and race conditions if run against the shared public schema.
-"""
-
-import tempfile
-import uuid
-import zipfile
-from pathlib import Path
-
-import asyncpg
-import pytest
-import pytest_asyncio
-
-from hindsight_api.admin.cli import _backup, _restore, BACKUP_TABLES
-from hindsight_api.migrations import run_migrations
-
-
-# Run these tests sequentially since they do full DB backup/restore
-pytestmark = pytest.mark.xdist_group(name="backup_restore")
-
-
-@pytest_asyncio.fixture(scope="function")
-async def backup_test_schema(pg0_db_url, embeddings):
-    """Create an isolated schema for backup/restore tests.
-
-    Uses a unique schema name per test invocation to avoid conflicts with
-    parallel test runs or leftover state from interrupted runs.
-
-    Returns a tuple of (db_url, schema_name, fq_helper, embeddings).
-    """
-    # Initialize embeddings if not already done
-    await embeddings.initialize()
-
-    # Use unique schema name to avoid conflicts
-    schema_name = f"backup_test_{uuid.uuid4().hex[:8]}"
-
-    def _fq(table: str) -> str:
-        """Get fully-qualified table name in test schema."""
-        return f"{schema_name}.{table}"
-
-    conn = await asyncpg.connect(pg0_db_url)
-    try:
-        await conn.execute(f"CREATE SCHEMA {schema_name}")
-    finally:
-        await conn.close()
-
-    # Run migrations on the isolated schema
-    run_migrations(pg0_db_url, schema=schema_name)
-
-    yield pg0_db_url, schema_name, _fq, embeddings
-
-    # Cleanup after test
-    conn = await asyncpg.connect(pg0_db_url)
-    try:
-        await conn.execute(f"DROP SCHEMA IF EXISTS {schema_name} CASCADE")
-    finally:
-        await conn.close()
-
-
-@pytest.mark.asyncio
-async def test_backup_restore_roundtrip(backup_test_schema):
-    """Test that backup and restore preserves all data correctly."""
-    db_url, schema_name, _fq, embeddings = backup_test_schema
-    bank_id = f"test-backup-{uuid.uuid4().hex[:8]}"
-    conn = await asyncpg.connect(db_url)
-
-    try:
-        # Create a bank
-        await conn.execute(
-            f"INSERT INTO {_fq('banks')} (bank_id) VALUES ($1) ON CONFLICT DO NOTHING",
-            bank_id,
-        )
-
-        # Create some test memory units with embeddings
-        # Convert embedding list to pgvector format string
-        embedding_list = embeddings.encode(["Test content about Alice"])[0]
-        embedding_str = "[" + ",".join(str(x) for x in embedding_list) + "]"
-        for text in [
-            "Alice is a software engineer who loves Python.",
-            "Bob works with Alice on the backend team.",
-            "The team uses PostgreSQL for their database.",
-        ]:
-            await conn.execute(
-                f"""INSERT INTO {_fq('memory_units')}
-                    (bank_id, text, fact_type, embedding, event_date)
-                    VALUES ($1, $2, 'world', $3::vector, NOW())""",
-                bank_id,
-                text,
-                embedding_str,
-            )
-
-        # Get counts before backup
-        counts_before = {}
-        for table in BACKUP_TABLES:
-            counts_before[table] = await conn.fetchval(f"SELECT COUNT(*) FROM {_fq(table)}")
-
-        # Verify we have data
-        assert counts_before["banks"] > 0
-        assert counts_before["memory_units"] > 0
-
-    finally:
-        await conn.close()
-
-    # Backup to a temp file
-    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as f:
-        backup_path = Path(f.name)
-
-    try:
-        manifest = await _backup(db_url, backup_path, schema=schema_name)
-
-        # Verify backup file exists and is valid
-        assert backup_path.exists()
-        assert backup_path.stat().st_size > 0
-
-        # Verify manifest
-        assert manifest["version"] == "1"
-        assert "created_at" in manifest
-        for table in BACKUP_TABLES:
-            assert table in manifest["tables"]
-            assert manifest["tables"][table]["rows"] == counts_before[table]
-
-        # Verify zip contents
-        with zipfile.ZipFile(backup_path, "r") as zf:
-            assert "manifest.json" in zf.namelist()
-            for table in BACKUP_TABLES:
-                assert f"{table}.bin" in zf.namelist()
-
-        # Clear all data
-        conn = await asyncpg.connect(db_url)
-        try:
-            for table in reversed(BACKUP_TABLES):
-                await conn.execute(f"TRUNCATE TABLE {_fq(table)} CASCADE")
-
-            # Verify data is gone
-            for table in BACKUP_TABLES:
-                count = await conn.fetchval(f"SELECT COUNT(*) FROM {_fq(table)}")
-                assert count == 0, f"Table {table} should be empty after truncate"
-        finally:
-            await conn.close()
-
-        # Restore from backup
-        await _restore(db_url, backup_path, schema=schema_name)
-
-        # Verify counts match original
-        conn = await asyncpg.connect(db_url)
-        try:
-            for table in BACKUP_TABLES:
-                count = await conn.fetchval(f"SELECT COUNT(*) FROM {_fq(table)}")
-                assert count == counts_before[table], f"Table {table} count mismatch after restore"
-
-            # Verify data content is preserved
-            texts = await conn.fetch(
-                f"SELECT text FROM {_fq('memory_units')} WHERE bank_id = $1",
-                bank_id,
-            )
-            text_content = " ".join(r["text"] for r in texts)
-            assert "Alice" in text_content or "software" in text_content
-        finally:
-            await conn.close()
-
-    finally:
-        # Cleanup
-        if backup_path.exists():
-            backup_path.unlink()
-
-
-@pytest.mark.asyncio
-async def test_backup_restore_preserves_all_column_types(backup_test_schema):
-    """Test that all column types are preserved: vectors, UUIDs, timestamps, JSONB."""
-    db_url, schema_name, _fq, embeddings = backup_test_schema
-    bank_id = f"test-types-{uuid.uuid4().hex[:8]}"
-    conn = await asyncpg.connect(db_url)
-
-    try:
-        # Create a bank
-        await conn.execute(
-            f"INSERT INTO {_fq('banks')} (bank_id) VALUES ($1) ON CONFLICT DO NOTHING",
-            bank_id,
-        )
-
-        # Create a memory unit with all column types
-        # Convert embedding list to pgvector format string
-        embedding_list = embeddings.encode(["John Smith engineer"])[0]
-        embedding_str = "[" + ",".join(str(x) for x in embedding_list) + "]"
-        await conn.execute(
-            f"""INSERT INTO {_fq('memory_units')}
-                (bank_id, text, fact_type, embedding, event_date, metadata)
-                VALUES ($1, $2, 'world', $3::vector, NOW(), $4)""",
-            bank_id,
-            "John Smith is a senior engineer at Acme Corp since 2020.",
-            embedding_str,
-            '{"key": "value"}',
-        )
-
-        # Create an entity
-        await conn.execute(
-            f"""INSERT INTO {_fq('entities')}
-                (bank_id, canonical_name, metadata)
-                VALUES ($1, $2, $3)""",
-            bank_id,
-            "John Smith",
-            '{"role": "engineer"}',
-        )
-
-        # Get original data
-        original_unit = await conn.fetchrow(
-            f"""SELECT id, embedding, event_date, created_at, metadata, text
-               FROM {_fq('memory_units')} WHERE bank_id = $1 LIMIT 1""",
-            bank_id,
-        )
-        original_entity = await conn.fetchrow(
-            f"""SELECT id, first_seen, last_seen, metadata, canonical_name
-               FROM {_fq('entities')} WHERE bank_id = $1 LIMIT 1""",
-            bank_id,
-        )
-        original_bank = await conn.fetchrow(
-            f"SELECT bank_id, created_at, updated_at FROM {_fq('banks')} WHERE bank_id = $1",
-            bank_id,
-        )
-    finally:
-        await conn.close()
-
-    assert original_unit is not None, "Should have created memory units"
-    assert original_unit["embedding"] is not None, "Should have embedding"
-    assert original_unit["id"] is not None, "Should have UUID"
-    assert original_entity is not None, "Should have created entities"
-
-    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as f:
-        backup_path = Path(f.name)
-
-    try:
-        await _backup(db_url, backup_path, schema=schema_name)
-
-        # Clear all data
-        conn = await asyncpg.connect(db_url)
-        try:
-            for table in reversed(BACKUP_TABLES):
-                await conn.execute(f"TRUNCATE TABLE {_fq(table)} CASCADE")
-        finally:
-            await conn.close()
-
-        await _restore(db_url, backup_path, schema=schema_name)
-
-        # Verify all column types are preserved exactly
-        conn = await asyncpg.connect(db_url)
-        try:
-            restored_unit = await conn.fetchrow(
-                f"""SELECT id, embedding, event_date, created_at, metadata, text
-                   FROM {_fq('memory_units')} WHERE bank_id = $1 LIMIT 1""",
-                bank_id,
-            )
-            restored_entity = await conn.fetchrow(
-                f"""SELECT id, first_seen, last_seen, metadata, canonical_name
-                   FROM {_fq('entities')} WHERE bank_id = $1 LIMIT 1""",
-                bank_id,
-            )
-            restored_bank = await conn.fetchrow(
-                f"SELECT bank_id, created_at, updated_at FROM {_fq('banks')} WHERE bank_id = $1",
-                bank_id,
-            )
-        finally:
-            await conn.close()
-
-        # Verify memory_units
-        assert restored_unit is not None, "Should have restored memory unit"
-        assert restored_unit["id"] == original_unit["id"], "UUID should match exactly"
-        assert restored_unit["text"] == original_unit["text"], "Text should match"
-        assert list(restored_unit["embedding"]) == list(original_unit["embedding"]), "Vector embedding should match exactly"
-        assert restored_unit["event_date"] == original_unit["event_date"], "Timestamp should match exactly"
-        assert restored_unit["created_at"] == original_unit["created_at"], "Created timestamp should match"
-        assert restored_unit["metadata"] == original_unit["metadata"], "JSONB metadata should match"
-
-        # Verify entities
-        assert restored_entity is not None, "Should have restored entity"
-        assert restored_entity["id"] == original_entity["id"], "Entity UUID should match"
-        assert restored_entity["canonical_name"] == original_entity["canonical_name"], "Entity name should match"
-        assert restored_entity["first_seen"] == original_entity["first_seen"], "Entity first_seen should match"
-        assert restored_entity["last_seen"] == original_entity["last_seen"], "Entity last_seen should match"
-        assert restored_entity["metadata"] == original_entity["metadata"], "Entity metadata should match"
-
-        # Verify banks
-        assert restored_bank is not None, "Should have restored bank"
-        assert restored_bank["bank_id"] == original_bank["bank_id"], "Bank ID should match"
-        assert restored_bank["created_at"] == original_bank["created_at"], "Bank created_at should match"
-
-    finally:
-        if backup_path.exists():
-            backup_path.unlink()
@@ -1,5 +1,5 @@
 """
-Tests for agent management API (profile, disposition).
+Tests for agent management API (profile, disposition, background).
 """
 import pytest
 import uuid
@@ -25,12 +25,15 @@ class TestAgentProfile:

        assert profile is not None
        assert "disposition" in profile
+        assert "background" in profile

        disposition = profile["disposition"]
        assert disposition.skepticism == 3
        assert disposition.literalism == 3
        assert disposition.empathy == 3

+        assert profile["background"] == ""
+
    @pytest.mark.asyncio
    async def test_update_agent_disposition(self, memory: MemoryEngine, request_context):
        """Test updating agent disposition traits."""
@@ -73,10 +76,63 @@ class TestAgentProfile:
        for agent in agents:
            assert "bank_id" in agent
            assert "disposition" in agent
+            assert "background" in agent
            assert "created_at" in agent
            assert "updated_at" in agent


+class TestAgentBackground:
+    """Tests for agent background management."""
+
+    @pytest.mark.asyncio
+    async def test_merge_agent_background(self, memory: MemoryEngine, request_context):
+        """Test merging agent background information."""
+        bank_id = unique_agent_id("test_profile_merge")
+
+        profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+        assert profile["background"] == ""
+
+        result1 = await memory.merge_bank_background(
+            bank_id,
+            "I was born in Texas",
+            update_disposition=False,
+            request_context=request_context,
+        )
+        assert "Texas" in result1["background"]
+
+        result2 = await memory.merge_bank_background(
+            bank_id,
+            "I have 10 years of startup experience",
+            update_disposition=False,
+            request_context=request_context,
+        )
+        assert "Texas" in result2["background"] or "startup" in result2["background"]
+
+        final_profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+        assert final_profile["background"] != ""
+
+    @pytest.mark.asyncio
+    async def test_merge_background_handles_conflicts(self, memory: MemoryEngine, request_context):
+        """Test that merging background handles conflicts (new overwrites old)."""
+        bank_id = unique_agent_id("test_profile_conflict")
+
+        result1 = await memory.merge_bank_background(
+            bank_id,
+            "I was born in Colorado",
+            update_disposition=False,
+            request_context=request_context,
+        )
+        assert "Colorado" in result1["background"]
+
+        result2 = await memory.merge_bank_background(
+            bank_id,
+            "You were born in Texas",
+            update_disposition=False,
+            request_context=request_context,
+        )
+        assert "Texas" in result2["background"]
+
+
 class TestAgentEndpoint:
    """Tests for agent PUT endpoint logic."""

@@ -91,6 +147,7 @@ class TestAgentEndpoint:
                literalism=5,
                empathy=2
            ),
+            background="I am a creative software engineer"
        )

        profile = await memory.get_bank_profile(bank_id, request_context=request_context)
@@ -102,10 +159,55 @@ class TestAgentEndpoint:
                request_context=request_context,
            )

+        if request.background is not None:
+            pool = await memory._get_pool()
+            async with pool.acquire() as conn:
+                await conn.execute(
+                    """
+                    UPDATE banks
+                    SET background = $2,
+                        updated_at = NOW()
+                    WHERE bank_id = $1
+                    """,
+                    bank_id,
+                    request.background
+                )
+
        final_profile = await memory.get_bank_profile(bank_id, request_context=request_context)

        assert final_profile["disposition"].skepticism == 4
        assert final_profile["disposition"].literalism == 5
+        assert final_profile["background"] == "I am a creative software engineer"
+
+    @pytest.mark.asyncio
+    async def test_put_agent_partial_update(self, memory: MemoryEngine, request_context):
+        """Test updating only background."""
+        bank_id = unique_agent_id("test_put_partial")
+
+        request = CreateBankRequest(
+            background="I am a data scientist"
+        )
+
+        profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        if request.background is not None:
+            pool = await memory._get_pool()
+            async with pool.acquire() as conn:
+                await conn.execute(
+                    """
+                    UPDATE banks
+                    SET background = $2,
+                        updated_at = NOW()
+                    WHERE bank_id = $1
+                    """,
+                    bank_id,
+                    request.background
+                )
+
+        final_profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        assert final_profile["disposition"].skepticism == 3  # Default
+        assert final_profile["background"] == "I am a data scientist"


 class TestAgentDispositionIntegration:
@@ -123,6 +225,13 @@ class TestAgentDispositionIntegration:
        }
        await memory.update_bank_disposition(bank_id, disposition, request_context=request_context)

+        await memory.merge_bank_background(
+            bank_id,
+            "I am a creative artist who values innovation over tradition",
+            update_disposition=False,
+            request_context=request_context,
+        )
+
        await memory.retain_batch_async(
            bank_id=bank_id,
            contents=[
@@ -1,223 +0,0 @@
-"""
-Test suite for causal relations extraction and validation.
-
-Tests that:
-1. Causal relations only reference previous facts (target_index < current fact index)
-2. Invalid causal relation indices are rejected
-3. The new per-fact causal relations schema works correctly
-"""
-
-from datetime import datetime
-
-import pytest
-
-from hindsight_api import LLMConfig
-from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-
-
-class TestCausalRelationsValidation:
-    """Tests for causal relations index validation."""
-
-    @pytest.mark.asyncio
-    async def test_causal_relations_only_reference_previous_facts(self):
-        """
-        Test that causal relations can only reference facts that appear before them.
-
-        This test verifies the new schema that prevents hallucination of invalid
-        fact indices by constraining target_index to be less than the current fact's index.
-        """
-        # Text with clear causal chain
-        text = """
-        I lost my job in January due to company layoffs.
-        Because I lost my job, I couldn't pay my rent.
-        Since I couldn't afford rent, I had to move to a cheaper apartment.
-        After moving, I started looking for a new job.
-        """
-
-        context = "Personal life update"
-        llm_config = LLMConfig.for_memory()
-        event_date = datetime(2024, 3, 15)
-
-        facts, _, usage = await extract_facts_from_text(
-            text=text,
-            event_date=event_date,
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser",
-        )
-
-        assert len(facts) > 0, "Should extract at least one fact"
-
-        # Verify all causal relations reference valid previous facts
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    assert rel.target_fact_index < i, (
-                        f"Fact {i} has causal relation to fact {rel.target_fact_index}, "
-                        f"but target_index must be < current index ({i})"
-                    )
-                    assert rel.target_fact_index >= 0, (
-                        f"Fact {i} has negative causal relation index: {rel.target_fact_index}"
-                    )
-                    assert rel.relation_type in ["caused_by", "enabled_by", "prevented_by"], (
-                        f"Invalid relation_type: {rel.relation_type}"
-                    )
-
-    @pytest.mark.asyncio
-    async def test_first_fact_has_no_causal_relations(self):
-        """
-        Test that the first fact (index 0) cannot have causal relations.
-
-        Since causal relations can only reference previous facts,
-        and there are no facts before index 0, the first fact should
-        have no causal relations.
-        """
-        text = """
-        The user started a new machine learning project.
-        The project requires learning TensorFlow.
-        Learning TensorFlow is challenging but rewarding.
-        """
-
-        context = "Project update"
-        llm_config = LLMConfig.for_memory()
-        event_date = datetime(2024, 6, 1)
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=event_date,
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser",
-        )
-
-        assert len(facts) > 0, "Should extract at least one fact"
-
-        # First fact should have no causal relations (nothing to reference)
-        if facts[0].causal_relations:
-            # If there are causal relations on the first fact, they should be empty
-            # or the validation should have filtered them out
-            for rel in facts[0].causal_relations:
-                # This should never happen due to validation
-                assert False, (
-                    f"First fact should not have causal relations, "
-                    f"but found: target_index={rel.target_fact_index}"
-                )
-
-    @pytest.mark.asyncio
-    async def test_causal_chain_extraction(self):
-        """
-        Test that a clear causal chain is extracted with valid relations.
-        """
-        text = """
-        Emily got promoted to senior engineer last month.
-        Because of her promotion, she received a significant salary increase.
-        With the extra money, she decided to buy a new car.
-        """
-
-        context = "Personal achievement story"
-        llm_config = LLMConfig.for_memory()
-        event_date = datetime(2024, 7, 15)
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=event_date,
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser",
-        )
-
-        assert len(facts) > 0, "Should extract facts about the causal chain"
-
-        # Collect all causal relations
-        all_relations = []
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    all_relations.append({
-                        "from_fact": i,
-                        "to_fact": rel.target_fact_index,
-                        "type": rel.relation_type,
-                    })
-
-        # If causal relations were extracted, verify they form a valid chain
-        if all_relations:
-            for rel in all_relations:
-                assert rel["to_fact"] < rel["from_fact"], (
-                    f"Causal relation from fact {rel['from_fact']} to fact {rel['to_fact']} "
-                    f"is invalid (target must be < source)"
-                )
-
-    @pytest.mark.asyncio
-    async def test_token_efficiency_with_causal_relations(self):
-        """
-        Test that causal relations don't cause excessive output tokens.
-
-        This test verifies that the new schema (per-fact causal relations
-        with index constraints) doesn't waste tokens on invalid relations.
-        """
-        text = """
-        The company announced budget cuts in Q1.
-        Due to the budget cuts, the marketing team was reduced.
-        The reduced team meant fewer campaigns could be run.
-        With fewer campaigns, lead generation dropped.
-        Lower leads resulted in decreased sales.
-        """
-
-        context = "Business impact analysis"
-        llm_config = LLMConfig.for_memory()
-        event_date = datetime(2024, 4, 1)
-
-        facts, _, usage = await extract_facts_from_text(
-            text=text,
-            event_date=event_date,
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser",
-        )
-
-        assert len(facts) > 0, "Should extract facts"
-
-        # Calculate output/input ratio
-        if usage.input_tokens > 0:
-            ratio = usage.output_tokens / usage.input_tokens
-            # The ratio should be reasonable (< 5x) with the new schema
-            # Previously it could be 7-10x due to hallucinated indices
-            assert ratio < 6, (
-                f"Output/input token ratio {ratio:.2f}x is too high. "
-                f"Input: {usage.input_tokens}, Output: {usage.output_tokens}"
-            )
-
-    @pytest.mark.asyncio
-    async def test_relation_types_are_backward_looking(self):
-        """
-        Test that all relation types describe how the current fact
-        relates to a previous fact (caused_by, enabled_by, prevented_by).
-        """
-        text = """
-        Alice learned Python programming.
-        Because she knew Python, she got a job as a data scientist.
-        Her data science skills enabled her to lead the analytics team.
-        """
-
-        context = "Career progression"
-        llm_config = LLMConfig.for_memory()
-        event_date = datetime(2024, 5, 1)
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=event_date,
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser",
-        )
-
-        # Verify relation types are all backward-looking
-        valid_types = {"caused_by", "enabled_by", "prevented_by"}
-
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    assert rel.relation_type in valid_types, (
-                        f"Invalid relation_type '{rel.relation_type}'. "
-                        f"Must be one of: {valid_types}"
-                    )
@@ -1,202 +0,0 @@
-"""
-Test suite for causal relationship extraction.
-
-Tests that the fact extraction system correctly identifies and validates
-causal relationships between facts, with valid indices.
-"""
-
-from datetime import datetime
-
-import pytest
-
-from hindsight_api import LLMConfig
-from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-
-
-class TestCausalRelationships:
-    """Tests for causal relationship extraction and validation."""
-
-    @pytest.mark.asyncio
-    async def test_causal_chain_extraction(self):
-        """
-        Test that a clear causal chain is extracted with valid relationships.
-
-        Story: Lost job -> couldn't pay rent -> had to move -> found new apartment
-
-        This is a 4-fact causal chain where each fact causes the next.
-        The extracted causal relations should have valid indices (0-3).
-        """
-        text = """
-I lost my job at the tech company in January because of layoffs.
-Because I lost my job, I couldn't pay my rent anymore.
-Since I couldn't afford rent, I had to move out of my apartment.
-After searching for weeks, I finally found a cheaper apartment in Brooklyn.
-"""
-
-        context = "Personal story about housing change"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 3, 15), context=context, llm_config=llm_config, agent_name="TestUser"
-        )
-
-        assert len(facts) >= 3, f"Should extract at least 3 facts from the causal chain. Got {len(facts)}"
-
-        # Collect all causal relations from all facts
-        all_causal_relations = []
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    all_causal_relations.append(
-                        {
-                            "from_fact_index": i,
-                            "to_fact_index": rel.target_fact_index,
-                            "relation_type": rel.relation_type,
-                            "strength": rel.strength,
-                            "from_fact_text": fact.fact[:50],
-                        }
-                    )
-
-        # Verify that ALL causal relation indices are valid
-        # New constraint: target_index must be < from_fact_index (can only reference PREVIOUS facts)
-        num_facts = len(facts)
-        invalid_relations = []
-        for rel in all_causal_relations:
-            # Must be non-negative and less than the current fact's index
-            if rel["to_fact_index"] < 0 or rel["to_fact_index"] >= rel["from_fact_index"]:
-                invalid_relations.append(rel)
-
-        assert len(invalid_relations) == 0, (
-            f"Found {len(invalid_relations)} causal relations with invalid indices! "
-            f"Each target_fact_index must be < from_fact_index (can only reference previous facts). "
-            f"Invalid relations: {invalid_relations}"
-        )
-
-        # Should have at least some causal relations extracted
-        assert len(all_causal_relations) >= 2, (
-            f"Should extract at least 2 causal relationships from this clear chain. "
-            f"Got {len(all_causal_relations)}: {all_causal_relations}"
-        )
-
-        # Verify relation types are valid (passive only - facts reference PREVIOUS facts)
-        valid_types = {"caused_by", "enabled_by", "prevented_by"}
-        for rel in all_causal_relations:
-            assert rel["relation_type"] in valid_types, (
-                f"Invalid relation_type '{rel['relation_type']}'. Must be one of {valid_types}"
-            )
-
-    @pytest.mark.asyncio
-    async def test_complex_causal_web(self):
-        """
-        Test a more complex scenario with multiple interconnected causes.
-
-        This tests the LLM's ability to identify multiple causal links and
-        ensure all referenced indices exist.
-        """
-        text = """
-The heavy rain caused flooding in the basement.
-The flooding damaged the electrical system.
-Because of the electrical damage, we had to call an electrician.
-The electrician found that the wiring was old and needed replacement.
-We decided to renovate the entire basement while fixing the wiring.
-The renovation took three months and cost $15,000.
-"""
-
-        context = "Home repair story"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 6, 1), context=context, llm_config=llm_config, agent_name="TestUser"
-        )
-
-        assert len(facts) >= 4, f"Should extract at least 4 facts. Got {len(facts)}"
-
-        # Validate all causal relation indices (must reference PREVIOUS facts only)
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    assert 0 <= rel.target_fact_index < i, (
-                        f"Fact {i} has causal relation to invalid index {rel.target_fact_index}. "
-                        f"Must reference previous facts only (valid range: 0 to {i - 1}). "
-                        f"Fact text: {fact.fact[:80]}..."
-                    )
-
-    @pytest.mark.asyncio
-    async def test_no_self_referencing_causal_relations(self):
-        """
-        Test that facts don't have causal relations pointing to themselves.
-        """
-        text = """
-I started learning Python because I wanted to automate my work tasks.
-Learning Python led me to discover machine learning.
-Machine learning fascinated me so much that I changed my career to data science.
-"""
-
-        context = "Career change story"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 1, 1), context=context, llm_config=llm_config, agent_name="TestUser"
-        )
-
-        # Check no fact references itself
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    assert rel.target_fact_index != i, (
-                        f"Fact {i} has a self-referencing causal relation! Fact text: {fact.fact}"
-                    )
-
-    @pytest.mark.asyncio
-    async def test_bidirectional_causal_relationships(self):
-        """
-        Test that bidirectional causal relationships (causes and caused_by)
-        are handled correctly.
-        """
-        text = """
-My promotion at work caused me to move to New York.
-Moving to New York was caused by my promotion at work.
-The new role enabled me to lead a team of engineers.
-"""
-
-        context = "Work promotion story"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 2, 15), context=context, llm_config=llm_config, agent_name="TestUser"
-        )
-
-        # Validate all indices (must reference PREVIOUS facts only)
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    assert 0 <= rel.target_fact_index < i, (
-                        f"Invalid target_fact_index {rel.target_fact_index} in fact {i}. "
-                        f"Must reference previous facts only (valid range: 0 to {i - 1})"
-                    )
-
-    @pytest.mark.asyncio
-    async def test_causal_relation_strength_values(self):
-        """
-        Test that causal relation strength values are within valid range [0.0, 1.0].
-        """
-        text = """
-The stock market crash directly caused the company to lay off employees.
-The layoffs indirectly led to reduced consumer spending in the area.
-Reduced spending somewhat affected local businesses.
-"""
-
-        context = "Economic impact story"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 4, 1), context=context, llm_config=llm_config, agent_name="TestUser"
-        )
-
-        for i, fact in enumerate(facts):
-            if fact.causal_relations:
-                for rel in fact.causal_relations:
-                    assert 0.0 <= rel.strength <= 1.0, (
-                        f"Causal relation strength {rel.strength} is outside valid range [0.0, 1.0]. "
-                        f"Fact {i}: {fact.fact[:50]}..."
-                    )
@@ -1,607 +0,0 @@
-"""
-Tests for custom embedding dimensions and automatic dimension detection.
-
-Uses isolated PostgreSQL schemas to avoid affecting other tests.
-Includes tests for:
- Automatic embedding dimension detection and database schema adjustment
- OpenAI embeddings provider with 1536 dimensions
-"""
-
-import asyncio
-import os
-import pytest
-from datetime import datetime
-from sqlalchemy import create_engine, text
-
-from hindsight_api import MemoryEngine, RequestContext
-from hindsight_api.engine.embeddings import LocalSTEmbeddings, OpenAIEmbeddings, CohereEmbeddings
-from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder, CohereCrossEncoder
-from hindsight_api.engine.query_analyzer import DateparserQueryAnalyzer
-from hindsight_api.engine.task_backend import SyncTaskBackend
-from hindsight_api.extensions import TenantExtension, TenantContext
-from hindsight_api.migrations import run_migrations, ensure_embedding_dimension
-
-
-# =============================================================================
-# Shared Utilities
-# =============================================================================
-
-
-class SchemaTenantExtension(TenantExtension):
-    """Tenant extension that routes all requests to a specific schema (for testing)."""
-
-    def __init__(self, schema_name: str):
-        self.schema_name = schema_name
-
-    async def authenticate(self, request_context: RequestContext) -> TenantContext:
-        return TenantContext(schema_name=self.schema_name)
-
-
-def get_test_schema(prefix: str, worker_id: str) -> str:
-    """Get unique schema name per xdist worker."""
-    if worker_id == "master" or not worker_id:
-        return prefix
-    return f"{prefix}_{worker_id}"
-
-
-def create_isolated_schema(db_url: str, schema_name: str, dimension: int | None = None):
-    """Create an isolated schema with migrations and optional dimension adjustment."""
-    engine = create_engine(db_url)
-
-    # Create schema (drop first if exists from previous failed run)
-    with engine.connect() as conn:
-        conn.execute(text(f"DROP SCHEMA IF EXISTS {schema_name} CASCADE"))
-        conn.execute(text(f"CREATE SCHEMA {schema_name}"))
-        conn.commit()
-
-    # Run migrations in the isolated schema
-    run_migrations(db_url, schema=schema_name)
-
-    # Adjust embedding dimension if specified
-    if dimension is not None:
-        ensure_embedding_dimension(db_url, dimension, schema=schema_name)
-
-
-def drop_schema(db_url: str, schema_name: str):
-    """Drop an isolated schema."""
-    engine = create_engine(db_url)
-    with engine.connect() as conn:
-        conn.execute(text(f"DROP SCHEMA IF EXISTS {schema_name} CASCADE"))
-        conn.commit()
-
-
-def get_column_dimension(db_url: str, schema: str = "public") -> int | None:
-    """Get the current embedding column dimension from the database."""
-    engine = create_engine(db_url)
-    with engine.connect() as conn:
-        result = conn.execute(
-            text("""
-                SELECT atttypmod
-                FROM pg_attribute a
-                JOIN pg_class c ON a.attrelid = c.oid
-                JOIN pg_namespace n ON c.relnamespace = n.oid
-                WHERE n.nspname = :schema
-                  AND c.relname = 'memory_units'
-                  AND a.attname = 'embedding'
-            """),
-            {"schema": schema},
-        ).scalar()
-        return result
-
-
-def get_row_count(db_url: str, schema: str = "public") -> int:
-    """Get the number of rows with embeddings in memory_units."""
-    engine = create_engine(db_url)
-    with engine.connect() as conn:
-        return conn.execute(
-            text(f"SELECT COUNT(*) FROM {schema}.memory_units WHERE embedding IS NOT NULL")
-        ).scalar()
-
-
-def insert_test_embedding(db_url: str, schema: str, dimension: int):
-    """Insert a test row with a dummy embedding."""
-    engine = create_engine(db_url)
-    embedding = [0.1] * dimension
-    embedding_str = "[" + ",".join(str(x) for x in embedding) + "]"
-
-    with engine.connect() as conn:
-        conn.execute(
-            text(f"""
-                INSERT INTO {schema}.memory_units (bank_id, text, embedding, event_date, fact_type)
-                VALUES ('test-bank', 'test text', '{embedding_str}'::vector, NOW(), 'world')
-            """)
-        )
-        conn.commit()
-
-
-def clear_embeddings(db_url: str, schema: str):
-    """Clear all rows from memory_units."""
-    engine = create_engine(db_url)
-    with engine.connect() as conn:
-        conn.execute(text(f"DELETE FROM {schema}.memory_units"))
-        conn.commit()
-
-
-# =============================================================================
-# Embedding Dimension Tests (Local Embeddings)
-# =============================================================================
-
-
-@pytest.fixture(scope="class")
-def dimension_test_schema(pg0_db_url, worker_id):
-    """Create an isolated schema for dimension tests."""
-    schema_name = get_test_schema("test_embed_dim", worker_id)
-    create_isolated_schema(pg0_db_url, schema_name)
-    yield pg0_db_url, schema_name
-    drop_schema(pg0_db_url, schema_name)
-
-
-class TestEmbeddingDimension:
-    """Tests for embedding dimension detection and adjustment."""
-
-    def test_dimension_matches_no_change(self, dimension_test_schema):
-        """When dimension matches, no changes should be made."""
-        db_url, schema = dimension_test_schema
-
-        # Get initial dimension (should be 384 from migration)
-        initial_dim = get_column_dimension(db_url, schema)
-        assert initial_dim == 384, f"Expected 384, got {initial_dim}"
-
-        # Call ensure_embedding_dimension with matching dimension
-        ensure_embedding_dimension(db_url, 384, schema=schema)
-
-        # Dimension should still be 384
-        assert get_column_dimension(db_url, schema) == 384
-
-    def test_dimension_change_empty_table(self, dimension_test_schema):
-        """When table is empty, dimension can be changed."""
-        db_url, schema = dimension_test_schema
-
-        # Ensure table is empty
-        clear_embeddings(db_url, schema)
-        assert get_row_count(db_url, schema) == 0
-
-        # Change dimension to 768
-        ensure_embedding_dimension(db_url, 768, schema=schema)
-
-        # Verify dimension changed
-        new_dim = get_column_dimension(db_url, schema)
-        assert new_dim == 768, f"Expected 768, got {new_dim}"
-
-        # Change back to 384 for other tests
-        ensure_embedding_dimension(db_url, 384, schema=schema)
-        assert get_column_dimension(db_url, schema) == 384
-
-    def test_dimension_change_blocked_with_data(self, dimension_test_schema):
-        """When table has data, dimension change should be blocked."""
-        db_url, schema = dimension_test_schema
-
-        # Ensure table is empty first
-        clear_embeddings(db_url, schema)
-
-        # Insert a test row with 384-dim embedding
-        insert_test_embedding(db_url, schema, 384)
-        assert get_row_count(db_url, schema) == 1
-
-        # Try to change dimension - should raise error
-        with pytest.raises(RuntimeError) as exc_info:
-            ensure_embedding_dimension(db_url, 768, schema=schema)
-
-        assert "Cannot change embedding dimension" in str(exc_info.value)
-        assert "1 rows with embeddings" in str(exc_info.value)
-
-        # Dimension should be unchanged
-        assert get_column_dimension(db_url, schema) == 384
-
-        # Cleanup
-        clear_embeddings(db_url, schema)
-
-    def test_local_embeddings_dimension_detection(self, embeddings):
-        """Test that LocalSTEmbeddings correctly detects dimension."""
-        # Initialize embeddings if not already done
-        loop = asyncio.new_event_loop()
-        try:
-            loop.run_until_complete(embeddings.initialize())
-        finally:
-            loop.close()
-
-        # bge-small-en-v1.5 produces 384-dim embeddings
-        assert embeddings.dimension == 384
-
-        # Verify by generating an actual embedding
-        result = embeddings.encode(["test"])
-        assert len(result) == 1
-        assert len(result[0]) == 384
-
-
-# =============================================================================
-# OpenAI Embeddings Tests
-# =============================================================================
-
-
-def has_openai_api_key() -> bool:
-    """Check if OpenAI API key is available."""
-    return bool(os.environ.get("HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY"))
-
-
-def get_openai_api_key() -> str:
-    """Get OpenAI API key from environment."""
-    return os.environ.get("HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY", "")
-
-
-@pytest.fixture(scope="module")
-def openai_embeddings():
-    """Create OpenAI embeddings instance."""
-    if not has_openai_api_key():
-        pytest.skip("OpenAI API key not available (set HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY)")
-
-    embeddings = OpenAIEmbeddings(
-        api_key=get_openai_api_key(),
-        model="text-embedding-3-small",
-    )
-    loop = asyncio.new_event_loop()
-    try:
-        loop.run_until_complete(embeddings.initialize())
-    finally:
-        loop.close()
-    return embeddings
-
-
-@pytest.fixture(scope="module")
-def openai_test_schema(pg0_db_url, worker_id, openai_embeddings):
-    """Create an isolated schema for OpenAI embedding tests."""
-    schema_name = get_test_schema("test_openai_embed", worker_id)
-    create_isolated_schema(pg0_db_url, schema_name, dimension=openai_embeddings.dimension)
-    yield pg0_db_url, schema_name
-    drop_schema(pg0_db_url, schema_name)
-
-
-@pytest.fixture
-def cross_encoder():
-    """Provide a cross encoder for tests."""
-    return LocalSTCrossEncoder()
-
-
-@pytest.fixture
-def query_analyzer():
-    """Provide a query analyzer for tests."""
-    return DateparserQueryAnalyzer()
-
-
-@pytest.fixture
-def test_bank_id():
-    """Provide a unique bank ID for this test run."""
-    return f"openai_test_{datetime.now().timestamp()}"
-
-
-@pytest.fixture
-def request_context():
-    """Provide a default RequestContext for tests."""
-    return RequestContext()
-
-
-class TestOpenAIEmbeddings:
-    """Tests for OpenAI embeddings provider."""
-
-    def test_openai_embeddings_initialization(self, openai_embeddings):
-        """Test that OpenAI embeddings initializes correctly."""
-        assert openai_embeddings.dimension == 1536
-        assert openai_embeddings.provider_name == "openai"
-
-    def test_openai_embeddings_encode(self, openai_embeddings):
-        """Test that OpenAI embeddings can encode text."""
-        texts = ["Hello, world!", "This is a test."]
-        embeddings = openai_embeddings.encode(texts)
-
-        assert len(embeddings) == 2
-        assert len(embeddings[0]) == 1536
-        assert len(embeddings[1]) == 1536
-        assert all(isinstance(x, float) for x in embeddings[0])
-
-    @pytest.mark.asyncio
-    async def test_openai_embeddings_retain_recall(
-        self,
-        openai_test_schema,
-        openai_embeddings,
-        cross_encoder,
-        query_analyzer,
-        test_bank_id,
-        request_context,
-    ):
-        """Test retain and recall operations with OpenAI embeddings."""
-        db_url, schema_name = openai_test_schema
-
-        memory = MemoryEngine(
-            db_url=db_url,
-            memory_llm_provider=os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq"),
-            memory_llm_api_key=os.getenv("HINDSIGHT_API_LLM_API_KEY"),
-            memory_llm_model=os.getenv("HINDSIGHT_API_LLM_MODEL", "openai/gpt-oss-120b"),
-            memory_llm_base_url=os.getenv("HINDSIGHT_API_LLM_BASE_URL") or None,
-            embeddings=openai_embeddings,
-            cross_encoder=cross_encoder,
-            query_analyzer=query_analyzer,
-            pool_min_size=1,
-            pool_max_size=3,
-            run_migrations=False,
-            tenant_extension=SchemaTenantExtension(schema_name),
-            task_backend=SyncTaskBackend(),
-        )
-
-        try:
-            await memory.initialize()
-
-            # Store some memories
-            await memory.retain_async(
-                bank_id=test_bank_id,
-                content="Alice works as a software engineer at Google.",
-                context="career discussion",
-                request_context=request_context,
-            )
-
-            await memory.retain_async(
-                bank_id=test_bank_id,
-                content="Bob is a data scientist specializing in machine learning.",
-                context="team introductions",
-                request_context=request_context,
-            )
-
-            # Recall memories
-            result = await memory.recall_async(
-                bank_id=test_bank_id,
-                query="Who works in technology?",
-                request_context=request_context,
-            )
-
-            assert result is not None
-            assert len(result.results) > 0
-
-            memory_texts = [m.text for m in result.results]
-            assert any(
-                "Alice" in text or "Bob" in text or "software" in text or "data scientist" in text
-                for text in memory_texts
-            ), f"Expected to find relevant memories, got: {memory_texts}"
-
-        finally:
-            try:
-                if memory._pool and not memory._pool._closing:
-                    await memory.close()
-            except Exception:
-                pass
-
-    @pytest.mark.asyncio
-    async def test_openai_embeddings_batch_retain(
-        self,
-        openai_test_schema,
-        openai_embeddings,
-        cross_encoder,
-        query_analyzer,
-        test_bank_id,
-        request_context,
-    ):
-        """Test batch retain with OpenAI embeddings."""
-        db_url, schema_name = openai_test_schema
-
-        memory = MemoryEngine(
-            db_url=db_url,
-            memory_llm_provider=os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq"),
-            memory_llm_api_key=os.getenv("HINDSIGHT_API_LLM_API_KEY"),
-            memory_llm_model=os.getenv("HINDSIGHT_API_LLM_MODEL", "openai/gpt-oss-120b"),
-            memory_llm_base_url=os.getenv("HINDSIGHT_API_LLM_BASE_URL") or None,
-            embeddings=openai_embeddings,
-            cross_encoder=cross_encoder,
-            query_analyzer=query_analyzer,
-            pool_min_size=1,
-            pool_max_size=3,
-            run_migrations=False,
-            tenant_extension=SchemaTenantExtension(schema_name),
-            task_backend=SyncTaskBackend(),
-        )
-
-        try:
-            await memory.initialize()
-
-            contents = [
-                {"content": "Python is my favorite programming language.", "context": "preferences"},
-                {"content": "I prefer dark mode for all my applications.", "context": "preferences"},
-                {"content": "Coffee is essential for morning productivity.", "context": "habits"},
-            ]
-
-            result = await memory.retain_batch_async(
-                bank_id=test_bank_id,
-                contents=contents,
-                request_context=request_context,
-            )
-
-            assert len(result) == 3
-
-            recall_result = await memory.recall_async(
-                bank_id=test_bank_id,
-                query="What are my preferences?",
-                request_context=request_context,
-            )
-
-            assert recall_result is not None
-            assert len(recall_result.results) > 0
-
-        finally:
-            try:
-                if memory._pool and not memory._pool._closing:
-                    await memory.close()
-            except Exception:
-                pass
-
-
-# =============================================================================
-# Cohere Embeddings Tests
-# =============================================================================
-
-
-def has_cohere_api_key() -> bool:
-    """Check if Cohere API key is available."""
-    return bool(os.environ.get("COHERE_API_KEY"))
-
-
-def get_cohere_api_key() -> str:
-    """Get Cohere API key from environment."""
-    return os.environ.get("COHERE_API_KEY", "")
-
-
-@pytest.fixture(scope="module")
-def cohere_embeddings():
-    """Create Cohere embeddings instance."""
-    if not has_cohere_api_key():
-        pytest.skip("Cohere API key not available (set COHERE_API_KEY)")
-
-    embeddings = CohereEmbeddings(
-        api_key=get_cohere_api_key(),
-        model="embed-english-v3.0",
-    )
-    loop = asyncio.new_event_loop()
-    try:
-        loop.run_until_complete(embeddings.initialize())
-    finally:
-        loop.close()
-    return embeddings
-
-
-@pytest.fixture(scope="module")
-def cohere_cross_encoder():
-    """Create Cohere cross-encoder instance."""
-    if not has_cohere_api_key():
-        pytest.skip("Cohere API key not available (set COHERE_API_KEY)")
-
-    cross_encoder = CohereCrossEncoder(
-        api_key=get_cohere_api_key(),
-        model="rerank-english-v3.0",
-    )
-    loop = asyncio.new_event_loop()
-    try:
-        loop.run_until_complete(cross_encoder.initialize())
-    finally:
-        loop.close()
-    return cross_encoder
-
-
-@pytest.fixture(scope="module")
-def cohere_test_schema(pg0_db_url, worker_id, cohere_embeddings):
-    """Create an isolated schema for Cohere embedding tests."""
-    schema_name = get_test_schema("test_cohere_embed", worker_id)
-    create_isolated_schema(pg0_db_url, schema_name, dimension=cohere_embeddings.dimension)
-    yield pg0_db_url, schema_name
-    drop_schema(pg0_db_url, schema_name)
-
-
-class TestCohereEmbeddings:
-    """Tests for Cohere embeddings provider."""
-
-    def test_cohere_embeddings_initialization(self, cohere_embeddings):
-        """Test that Cohere embeddings initializes correctly."""
-        assert cohere_embeddings.dimension == 1024
-        assert cohere_embeddings.provider_name == "cohere"
-
-    def test_cohere_embeddings_encode(self, cohere_embeddings):
-        """Test that Cohere embeddings can encode text."""
-        texts = ["Hello, world!", "This is a test."]
-        embeddings = cohere_embeddings.encode(texts)
-
-        assert len(embeddings) == 2
-        assert len(embeddings[0]) == 1024
-        assert len(embeddings[1]) == 1024
-        assert all(isinstance(x, float) for x in embeddings[0])
-
-
-class TestCohereCrossEncoder:
-    """Tests for Cohere cross-encoder/reranker."""
-
-    def test_cohere_cross_encoder_initialization(self, cohere_cross_encoder):
-        """Test that Cohere cross-encoder initializes correctly."""
-        assert cohere_cross_encoder.provider_name == "cohere"
-
-    @pytest.mark.asyncio
-    async def test_cohere_cross_encoder_predict(self, cohere_cross_encoder):
-        """Test that Cohere cross-encoder can score pairs."""
-        pairs = [
-            ("What is the capital of France?", "Paris is the capital of France."),
-            ("What is the capital of France?", "The Eiffel Tower is in Paris."),
-            ("What is the capital of France?", "Python is a programming language."),
-        ]
-        scores = await cohere_cross_encoder.predict(pairs)
-
-        assert len(scores) == 3
-        assert all(isinstance(s, float) for s in scores)
-        # The first result should be most relevant
-        assert scores[0] > scores[2], "Direct answer should score higher than unrelated text"
-
-
-class TestCohereIntegration:
-    """Integration tests for Cohere embeddings with memory engine."""
-
-    @pytest.mark.asyncio
-    async def test_cohere_embeddings_retain_recall(
-        self,
-        cohere_test_schema,
-        cohere_embeddings,
-        cohere_cross_encoder,
-        query_analyzer,
-        request_context,
-    ):
-        """Test retain and recall operations with Cohere embeddings."""
-        db_url, schema_name = cohere_test_schema
-        test_bank_id = f"cohere_test_{datetime.now().timestamp()}"
-
-        memory = MemoryEngine(
-            db_url=db_url,
-            memory_llm_provider=os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq"),
-            memory_llm_api_key=os.getenv("HINDSIGHT_API_LLM_API_KEY"),
-            memory_llm_model=os.getenv("HINDSIGHT_API_LLM_MODEL", "openai/gpt-oss-120b"),
-            memory_llm_base_url=os.getenv("HINDSIGHT_API_LLM_BASE_URL") or None,
-            embeddings=cohere_embeddings,
-            cross_encoder=cohere_cross_encoder,
-            query_analyzer=query_analyzer,
-            pool_min_size=1,
-            pool_max_size=3,
-            run_migrations=False,
-            tenant_extension=SchemaTenantExtension(schema_name),
-            task_backend=SyncTaskBackend(),
-        )
-
-        try:
-            await memory.initialize()
-
-            # Store some memories
-            await memory.retain_async(
-                bank_id=test_bank_id,
-                content="Alice works as a software engineer at Google.",
-                context="career discussion",
-                request_context=request_context,
-            )
-
-            await memory.retain_async(
-                bank_id=test_bank_id,
-                content="Bob is a data scientist specializing in machine learning.",
-                context="team introductions",
-                request_context=request_context,
-            )
-
-            # Recall memories
-            result = await memory.recall_async(
-                bank_id=test_bank_id,
-                query="Who works in technology?",
-                request_context=request_context,
-            )
-
-            assert result is not None
-            assert len(result.results) > 0
-
-            memory_texts = [m.text for m in result.results]
-            assert any(
-                "Alice" in text or "Bob" in text or "software" in text or "data scientist" in text
-                for text in memory_texts
-            ), f"Expected to find relevant memories, got: {memory_texts}"
-
-        finally:
-            try:
-                if memory._pool and not memory._pool._closing:
-                    await memory.close()
-            except Exception:
-                pass
@@ -1,516 +0,0 @@
-"""Tests for emergent entity filtering."""
-
-import pytest
-from unittest.mock import AsyncMock, MagicMock
-
-from hindsight_api.engine.mental_models.emergent import (
-    build_mission_filter_prompt,
-    evaluate_emergent_models,
-    filter_candidates_by_mission,
-    MissionFilterResponse,
-    MissionFilterCandidate,
-)
-from hindsight_api.engine.mental_models.models import EmergentCandidate
-
-
-class TestBuildMissionFilterPrompt:
-    """Test prompt building for mission filtering."""
-
-    def test_prompt_contains_mission(self):
-        """Test that prompt includes the mission."""
-        candidates = [
-            EmergentCandidate(
-                name="Alice",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            )
-        ]
-        prompt = build_mission_filter_prompt("Be a PM for engineering team", candidates)
-        assert "Be a PM for engineering team" in prompt
-
-    def test_prompt_contains_candidates(self):
-        """Test that prompt includes all candidates."""
-        candidates = [
-            EmergentCandidate(
-                name="Alice Chen",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            ),
-            EmergentCandidate(
-                name="Project Phoenix",
-                detection_method="named_entity_extraction",
-                mention_count=5,
-            ),
-        ]
-        prompt = build_mission_filter_prompt("Track projects", candidates)
-        assert "Alice Chen" in prompt
-        assert "Project Phoenix" in prompt
-
-    def test_prompt_contains_rejection_guidance(self):
-        """Test that prompt contains guidance to reject generic entities."""
-        candidates = [
-            EmergentCandidate(
-                name="test",
-                detection_method="named_entity_extraction",
-                mention_count=1,
-            )
-        ]
-        prompt = build_mission_filter_prompt("Test mission", candidates)
-
-        # Should contain rejection guidance for generic terms
-        assert "promote=false" in prompt
-        assert "kids" in prompt  # Example of generic term to reject
-        assert "community" in prompt  # Example of abstract concept to reject
-        assert "motivation" in prompt  # Example of abstract concept to reject
-
-
-class TestFilterCandidatesByMission:
-    """Test the filter_candidates_by_mission function."""
-
-    @pytest.fixture
-    def mock_llm_config(self):
-        """Create a mock LLM config."""
-        config = MagicMock()
-        config.call = AsyncMock()
-        return config
-
-    async def test_empty_candidates(self, mock_llm_config):
-        """Test with empty candidate list."""
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="Test mission",
-            candidates=[],
-        )
-        assert result == []
-        mock_llm_config.call.assert_not_called()
-
-    async def test_no_mission_keeps_all(self, mock_llm_config):
-        """Test that no mission keeps all candidates (skips filtering)."""
-        candidates = [
-            EmergentCandidate(
-                name="Alice",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            )
-        ]
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="",  # Empty mission
-            candidates=candidates,
-        )
-        assert len(result) == 1
-        assert result[0].name == "Alice"
-        mock_llm_config.call.assert_not_called()
-
-    async def test_filters_by_promote_flag(self, mock_llm_config):
-        """Test that candidates are filtered by promote flag."""
-        candidates = [
-            EmergentCandidate(
-                name="Alice Chen",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            ),
-            EmergentCandidate(
-                name="community",
-                detection_method="named_entity_extraction",
-                mention_count=5,
-            ),
-        ]
-
-        # Mock LLM response - Alice is promoted, community is not
-        mock_llm_config.call.return_value = MissionFilterResponse(
-            candidates=[
-                MissionFilterCandidate(name="Alice Chen", promote=True, reason="Specific person"),
-                MissionFilterCandidate(name="community", promote=False, reason="Generic abstract concept"),
-            ]
-        )
-
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="Be a PM for engineering team",
-            candidates=candidates,
-        )
-
-        assert len(result) == 1
-        assert result[0].name == "Alice Chen"
-
-    async def test_rejects_generic_entities(self, mock_llm_config):
-        """Test that generic entities are rejected."""
-        # These are all generic/abstract terms that should be rejected
-        generic_names = [
-            "user", "support", "community", "family", "motivation",
-            "photo", "gratitude", "difference", "volunteering",
-            "kids", "veterans", "impact", "kindness", "encouragement",
-            "education", "nature", "joy", "positivity", "inspiration",
-            "help", "commitment", "passion", "energy", "connection",
-        ]
-        candidates = [
-            EmergentCandidate(
-                name=name,
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            )
-            for name in generic_names
-        ]
-
-        # Add some valid candidates
-        valid_candidates = [
-            EmergentCandidate(
-                name="John",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            ),
-            EmergentCandidate(
-                name="Maria",
-                detection_method="named_entity_extraction",
-                mention_count=8,
-            ),
-            EmergentCandidate(
-                name="Max",
-                detection_method="named_entity_extraction",
-                mention_count=6,
-            ),
-        ]
-        candidates.extend(valid_candidates)
-
-        # Mock LLM response - reject all generic, promote only specific names
-        response_candidates = [
-            MissionFilterCandidate(name=name, promote=False, reason="Generic/abstract term")
-            for name in generic_names
-        ]
-        response_candidates.extend([
-            MissionFilterCandidate(name=c.name, promote=True, reason="Specific person name")
-            for c in valid_candidates
-        ])
-
-        mock_llm_config.call.return_value = MissionFilterResponse(candidates=response_candidates)
-
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="Be a health coach",
-            candidates=candidates,
-        )
-
-        # Should only have John, Maria, and Max
-        result_names = {c.name for c in result}
-        assert result_names == {"John", "Maria", "Max"}
-
-    async def test_accepts_specific_named_entities(self, mock_llm_config):
-        """Test that specific named entities are accepted."""
-        # These should all be accepted
-        valid_names = [
-            "Alice Chen",       # Full name
-            "Dr. Smith",        # Title + name
-            "John",             # First name (when it's clearly a person)
-            "Google",           # Organization
-            "Frontend Team",    # Named team
-            "Project Phoenix",  # Named project
-            "NYC Office",       # Named place
-            "Q4 Planning",      # Named event
-            "Sprint 23 Review", # Named meeting
-        ]
-        candidates = [
-            EmergentCandidate(
-                name=name,
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            )
-            for name in valid_names
-        ]
-
-        # Mock LLM response - promote all
-        response_candidates = [
-            MissionFilterCandidate(name=name, promote=True, reason="Specific named entity")
-            for name in valid_names
-        ]
-        mock_llm_config.call.return_value = MissionFilterResponse(candidates=response_candidates)
-
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="Be a PM for engineering team",
-            candidates=candidates,
-        )
-
-        # Should have all valid names
-        result_names = {c.name for c in result}
-        assert result_names == set(valid_names)
-
-    async def test_llm_error_rejects_all_candidates(self, mock_llm_config):
-        """Test that LLM errors result in rejecting all candidates (fail-safe)."""
-        candidates = [
-            EmergentCandidate(
-                name="Alice",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            )
-        ]
-
-        mock_llm_config.call.side_effect = Exception("LLM error")
-
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="Test mission",
-            candidates=candidates,
-        )
-
-        # Should reject all candidates on error (fail-safe)
-        assert len(result) == 0
-
-    async def test_missing_candidate_in_response_is_rejected(self, mock_llm_config):
-        """Test that candidates not in LLM response are rejected by default."""
-        candidates = [
-            EmergentCandidate(
-                name="Alice",
-                detection_method="named_entity_extraction",
-                mention_count=10,
-            ),
-            EmergentCandidate(
-                name="Bob",
-                detection_method="named_entity_extraction",
-                mention_count=5,
-            ),
-        ]
-
-        # Mock LLM response - only includes Alice, not Bob
-        mock_llm_config.call.return_value = MissionFilterResponse(
-            candidates=[
-                MissionFilterCandidate(name="Alice", promote=True, reason="Specific person"),
-            ]
-        )
-
-        result = await filter_candidates_by_mission(
-            llm_config=mock_llm_config,
-            mission="Test mission",
-            candidates=candidates,
-        )
-
-        # Only Alice should be in result (Bob was missing from response, so rejected)
-        assert len(result) == 1
-        assert result[0].name == "Alice"
-
-
-class TestEvaluateEmergentModels:
-    """Test the evaluate_emergent_models function for cleanup of existing models."""
-
-    @pytest.fixture
-    def mock_llm_config(self):
-        """Create a mock LLM config."""
-        config = MagicMock()
-        config.call = AsyncMock()
-        return config
-
-    async def test_empty_models(self, mock_llm_config):
-        """Test with empty model list."""
-        result = await evaluate_emergent_models(
-            llm_config=mock_llm_config,
-            models=[],
-        )
-        assert result == []
-        mock_llm_config.call.assert_not_called()
-
-    async def test_removes_generic_models(self, mock_llm_config):
-        """Test that generic/abstract models are marked for removal."""
-        models = [
-            {"id": "id-kids", "name": "kids"},
-            {"id": "id-community", "name": "community"},
-            {"id": "id-motivation", "name": "motivation"},
-            {"id": "id-john", "name": "John"},
-            {"id": "id-maria", "name": "Maria"},
-        ]
-
-        # Mock LLM response - reject generic, keep specific names
-        mock_llm_config.call.return_value = MissionFilterResponse(
-            candidates=[
-                MissionFilterCandidate(name="kids", promote=False, reason="Generic category"),
-                MissionFilterCandidate(name="community", promote=False, reason="Abstract concept"),
-                MissionFilterCandidate(name="motivation", promote=False, reason="Abstract concept"),
-                MissionFilterCandidate(name="John", promote=True, reason="Person name"),
-                MissionFilterCandidate(name="Maria", promote=True, reason="Person name"),
-            ]
-        )
-
-        result = await evaluate_emergent_models(
-            llm_config=mock_llm_config,
-            models=models,
-        )
-
-        # Should return IDs of generic models to remove
-        assert set(result) == {"id-kids", "id-community", "id-motivation"}
-
-    async def test_keeps_specific_named_models(self, mock_llm_config):
-        """Test that specific named models are kept."""
-        models = [
-            {"id": "id-john", "name": "John"},
-            {"id": "id-google", "name": "Google"},
-            {"id": "id-project", "name": "Project Phoenix"},
-        ]
-
-        # Mock LLM response - keep all
-        mock_llm_config.call.return_value = MissionFilterResponse(
-            candidates=[
-                MissionFilterCandidate(name="John", promote=True, reason="Person name"),
-                MissionFilterCandidate(name="Google", promote=True, reason="Organization"),
-                MissionFilterCandidate(name="Project Phoenix", promote=True, reason="Named project"),
-            ]
-        )
-
-        result = await evaluate_emergent_models(
-            llm_config=mock_llm_config,
-            models=models,
-        )
-
-        # No models should be removed
-        assert result == []
-
-    async def test_llm_error_keeps_all_models(self, mock_llm_config):
-        """Test that LLM errors result in keeping all models (safe default)."""
-        models = [
-            {"id": "id-kids", "name": "kids"},
-            {"id": "id-john", "name": "John"},
-        ]
-
-        mock_llm_config.call.side_effect = Exception("LLM error")
-
-        result = await evaluate_emergent_models(
-            llm_config=mock_llm_config,
-            models=models,
-        )
-
-        # Should keep all models on error (return empty removal list)
-        assert result == []
-
-    async def test_missing_model_in_response_is_removed(self, mock_llm_config):
-        """Test that models not in LLM response are marked for removal."""
-        models = [
-            {"id": "id-alice", "name": "Alice"},
-            {"id": "id-bob", "name": "Bob"},
-        ]
-
-        # Mock LLM response - only includes Alice
-        mock_llm_config.call.return_value = MissionFilterResponse(
-            candidates=[
-                MissionFilterCandidate(name="Alice", promote=True, reason="Person name"),
-            ]
-        )
-
-        result = await evaluate_emergent_models(
-            llm_config=mock_llm_config,
-            models=models,
-        )
-
-        # Bob should be marked for removal (missing from response)
-        assert result == ["id-bob"]
-
-
-class TestRemovedEntitiesNotRepromoted:
-    """Test that entities removed by evaluation are not re-promoted.
-
-    This tests the fix for a bug where:
-    1. evaluate_emergent_models returns model IDs to remove (e.g., 'entity-maya')
-    2. We delete those models
-    3. detect_entity_candidates finds the same entities (now eligible since model was deleted)
-    4. filter_candidates_by_goal approves them (different LLM call)
-    5. BUG: We were re-promoting the same entities we just removed
-
-    The fix tracks removed entity_ids and excludes them from promotion.
-    """
-
-    async def test_removed_entity_ids_excluded_from_promotion(self):
-        """Test that entities whose models were removed are not re-promoted."""
-        from hindsight_api.engine.mental_models.models import EmergentCandidate
-
-        # Simulate the scenario from the bug:
-        # - existing_emergent has model 'entity-maya' with entity_id='uuid-maya'
-        # - evaluate_emergent_models says to remove 'entity-maya'
-        # - detect_entity_candidates returns 'Maya' with entity_id='uuid-maya' (now eligible)
-        # - filter_candidates_by_goal says to promote 'Maya'
-        # - But we should NOT promote because we just removed it
-
-        existing_emergent = [
-            {"id": "entity-maya", "name": "Maya", "entity_id": "uuid-maya"},
-            {"id": "entity-alex", "name": "Alex", "entity_id": "uuid-alex"},
-            {"id": "entity-john", "name": "John", "entity_id": "uuid-john"},  # This one will be kept
-        ]
-
-        # Models to remove (evaluate_emergent_models would return these)
-        models_to_remove = ["entity-maya", "entity-alex"]
-
-        # Build model_id -> entity_id mapping (this is what the fix does)
-        model_to_entity = {m["id"]: m.get("entity_id") for m in existing_emergent}
-
-        # Track removed entity_ids
-        removed_entity_ids: set[str] = set()
-        for model_id in models_to_remove:
-            entity_id = model_to_entity.get(model_id)
-            if entity_id:
-                removed_entity_ids.add(str(entity_id))
-
-        # Verify we tracked the right entity_ids
-        assert removed_entity_ids == {"uuid-maya", "uuid-alex"}
-
-        # Now simulate candidates that were detected (includes removed entities)
-        candidates = [
-            EmergentCandidate(
-                name="Maya", entity_id="uuid-maya", detection_method="named_entity", mention_count=10
-            ),
-            EmergentCandidate(
-                name="Alex", entity_id="uuid-alex", detection_method="named_entity", mention_count=8
-            ),
-            EmergentCandidate(
-                name="NewPerson", entity_id="uuid-new", detection_method="named_entity", mention_count=5
-            ),
-        ]
-
-        # Filter out candidates whose entity was just removed (the fix)
-        filtered_candidates = [c for c in candidates if c.entity_id not in removed_entity_ids]
-
-        # Only NewPerson should remain - Maya and Alex were removed and should not be re-promoted
-        assert len(filtered_candidates) == 1
-        assert filtered_candidates[0].name == "NewPerson"
-        assert filtered_candidates[0].entity_id == "uuid-new"
-
-    async def test_candidates_without_matching_removal_are_kept(self):
-        """Test that candidates not in the removed set are still promoted."""
-        from hindsight_api.engine.mental_models.models import EmergentCandidate
-
-        # No models removed
-        removed_entity_ids: set[str] = set()
-
-        candidates = [
-            EmergentCandidate(
-                name="Alice", entity_id="uuid-alice", detection_method="named_entity", mention_count=10
-            ),
-            EmergentCandidate(
-                name="Bob", entity_id="uuid-bob", detection_method="named_entity", mention_count=8
-            ),
-        ]
-
-        # Filter (should keep all since nothing was removed)
-        filtered_candidates = [c for c in candidates if c.entity_id not in removed_entity_ids]
-
-        assert len(filtered_candidates) == 2
-        assert {c.name for c in filtered_candidates} == {"Alice", "Bob"}
-
-    async def test_partial_removal_keeps_other_candidates(self):
-        """Test that only removed entities are excluded, others pass through."""
-        from hindsight_api.engine.mental_models.models import EmergentCandidate
-
-        # Only one entity removed
-        removed_entity_ids = {"uuid-removed"}
-
-        candidates = [
-            EmergentCandidate(
-                name="Removed", entity_id="uuid-removed", detection_method="named_entity", mention_count=10
-            ),
-            EmergentCandidate(
-                name="Kept1", entity_id="uuid-kept1", detection_method="named_entity", mention_count=8
-            ),
-            EmergentCandidate(
-                name="Kept2", entity_id="uuid-kept2", detection_method="named_entity", mention_count=5
-            ),
-        ]
-
-        filtered_candidates = [c for c in candidates if c.entity_id not in removed_entity_ids]
-
-        assert len(filtered_candidates) == 2
-        assert {c.name for c in filtered_candidates} == {"Kept1", "Kept2"}
@@ -17,8 +17,6 @@ from hindsight_api.extensions import (
    RecallResult,
    ReflectContext,
    ReflectResultContext,
-    RefreshMentalModelContext,
-    RefreshMentalModelResult,
    RequestContext,
    RetainContext,
    RetainResult,
@@ -95,7 +93,6 @@ class RateLimitingValidator(OperationValidatorExtension):
        self.retain_counts: dict[str, int] = defaultdict(int)
        self.recall_counts: dict[str, int] = defaultdict(int)
        self.reflect_counts: dict[str, int] = defaultdict(int)
-        self.refresh_mental_model_counts: dict[str, int] = defaultdict(int)

    async def validate_retain(self, ctx: RetainContext) -> ValidationResult:
        self.retain_counts[ctx.bank_id] += 1
@@ -121,16 +118,6 @@ class RateLimitingValidator(OperationValidatorExtension):
            )
        return ValidationResult.accept()

-    async def validate_refresh_mental_model(
-        self, ctx: RefreshMentalModelContext
-    ) -> ValidationResult:
-        self.refresh_mental_model_counts[ctx.bank_id] += 1
-        if self.refresh_mental_model_counts[ctx.bank_id] > self.max_attempts:
-            return ValidationResult.reject(
-                f"Refresh mental model limit exceeded for bank {ctx.bank_id}"
-            )
-        return ValidationResult.accept()
-

 class TrackingValidator(OperationValidatorExtension):
    """
@@ -145,12 +132,10 @@ class TrackingValidator(OperationValidatorExtension):
        self.pre_retain_calls: list[RetainContext] = []
        self.pre_recall_calls: list[RecallContext] = []
        self.pre_reflect_calls: list[ReflectContext] = []
-        self.pre_refresh_mental_model_calls: list[RefreshMentalModelContext] = []
        # Post-hook tracking
        self.post_retain_calls: list[RetainResult] = []
        self.post_recall_calls: list[RecallResult] = []
        self.post_reflect_calls: list[ReflectResultContext] = []
-        self.post_refresh_mental_model_calls: list[RefreshMentalModelResult] = []

    async def validate_retain(self, ctx: RetainContext) -> ValidationResult:
        self.pre_retain_calls.append(ctx)
@@ -164,12 +149,6 @@ class TrackingValidator(OperationValidatorExtension):
        self.pre_reflect_calls.append(ctx)
        return ValidationResult.accept()

-    async def validate_refresh_mental_model(
-        self, ctx: RefreshMentalModelContext
-    ) -> ValidationResult:
-        self.pre_refresh_mental_model_calls.append(ctx)
-        return ValidationResult.accept()
-
    async def on_retain_complete(self, result: RetainResult) -> None:
        self.post_retain_calls.append(result)

@@ -179,11 +158,6 @@ class TrackingValidator(OperationValidatorExtension):
    async def on_reflect_complete(self, result: ReflectResultContext) -> None:
        self.post_reflect_calls.append(result)

-    async def on_refresh_mental_model_complete(
-        self, result: RefreshMentalModelResult
-    ) -> None:
-        self.post_refresh_mental_model_calls.append(result)
-

 class TestMemoryEngineValidation:
    """Tests for validation integration with MemoryEngine.
@@ -541,105 +515,6 @@ class TestOperationHooksParameters:
        assert len(validator.pre_recall_calls) == 1
        assert len(validator.post_recall_calls) == 1

-    @pytest.mark.asyncio
-    async def test_refresh_mental_model_pre_hook_receives_all_parameters(
-        self, memory_with_tracking_validator
-    ):
-        """Pre-refresh-mental-model hook receives all user-provided parameters."""
-        import uuid
-
-        memory, validator = memory_with_tracking_validator
-        bank_id = f"test-refresh-mm-params-{uuid.uuid4().hex[:8]}"
-        ctx = RequestContext(api_key="test-key")
-
-        # Create bank first (get_bank_profile auto-creates if needed)
-        await memory.get_bank_profile(bank_id, request_context=ctx)
-
-        # Create a pinned mental model
-        model = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Test Model",
-            description="Test description",
-            subtype="pinned",
-            request_context=ctx,
-        )
-
-        assert model is not None
-        model_id = model["id"]
-
-        # Attempt to refresh (may not actually refresh if no data, but hook should be called)
-        try:
-            await memory.refresh_mental_model(
-                bank_id=bank_id,
-                model_id=model_id,
-                request_context=ctx,
-            )
-        except Exception:
-            pass  # May fail if no data
-
-        # Check pre-hook was called
-        assert len(validator.pre_refresh_mental_model_calls) == 1
-        pre_ctx = validator.pre_refresh_mental_model_calls[0]
-        assert pre_ctx.bank_id == bank_id
-        assert pre_ctx.model_id == model_id
-        assert pre_ctx.request_context == ctx
-
-    @pytest.mark.asyncio
-    async def test_refresh_mental_model_post_hook_receives_token_usage(
-        self, memory_with_tracking_validator
-    ):
-        """Post-refresh-mental-model hook receives token usage information."""
-        import uuid
-
-        memory, validator = memory_with_tracking_validator
-        bank_id = f"test-refresh-mm-tokens-{uuid.uuid4().hex[:8]}"
-        ctx = RequestContext(api_key="test-key")
-
-        # Store some content first
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                {"content": "Alice is a software engineer who works on machine learning."},
-                {"content": "Alice enjoys hiking and outdoor activities on weekends."},
-                {"content": "Alice has been working at the company for 5 years."},
-            ],
-            request_context=ctx,
-        )
-
-        # Create a pinned mental model
-        model = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Alice Profile",
-            description="Profile of Alice including work and hobbies",
-            subtype="pinned",
-            request_context=ctx,
-        )
-
-        if model:
-            model_id = model["id"]
-
-            # Refresh the mental model
-            result = await memory.refresh_mental_model(
-                bank_id=bank_id,
-                model_id=model_id,
-                request_context=ctx,
-            )
-
-            # Check post-hook was called with token usage
-            if validator.post_refresh_mental_model_calls:
-                post_result = validator.post_refresh_mental_model_calls[0]
-                assert post_result.bank_id == bank_id
-                assert post_result.model_id == model_id
-                assert post_result.request_context == ctx
-                assert post_result.success is True
-                assert post_result.error is None
-
-                # Token usage should be populated (may be 0 if refresh was skipped)
-                assert post_result.total_tokens >= 0
-                assert post_result.input_tokens >= 0
-                assert post_result.output_tokens >= 0
-                assert post_result.duration_ms >= 0
-

 class TestTenantExtension:
    """Tests for TenantExtension and ApiKeyTenantExtension."""
@@ -1,103 +0,0 @@
-"""
-Test to analyze fact extraction token usage and identify optimization opportunities.
-"""
-import asyncio
-import logging
-import time
-from datetime import datetime
-
-import pytest
-
-from hindsight_api.config import get_config, clear_config_cache
-from hindsight_api.engine.llm_wrapper import LLMConfig
-from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-@pytest.fixture
-def llm_config():
-    """Create LLM config from environment."""
-    clear_config_cache()
-    config = get_config()
-    return LLMConfig(
-        provider=config.retain_llm_provider or config.llm_provider,
-        api_key=config.retain_llm_api_key or config.llm_api_key,
-        model=config.retain_llm_model or config.llm_model,
-        base_url=config.retain_llm_base_url or config.llm_base_url,
-    )
-
-
-@pytest.mark.asyncio
-async def test_fact_extraction_basic_analysis(llm_config):
-    """
-    Test fact extraction and analyze token usage with sample content.
-
-    This test helps identify:
-    1. How many facts are extracted
-    2. Token usage (input/output ratio)
-    3. Types of facts being extracted
-    """
-    content = """
-    Alice is a senior software engineer at TechCorp with 8 years of experience.
-    She has a Kubernetes certification (CKA) and leads the platform team.
-    Bob is her colleague who works on the frontend. He's been at the company for 3 years.
-    They're working on a new microservices migration project together.
-    The deadline for the first milestone is end of Q2.
-    Alice prefers to use Go for backend services while Bob advocates for TypeScript.
-    """
-
-    logger.info(f"Content length: {len(content)} chars (~{len(content) // 4} tokens)")
-
-    start_time = time.time()
-
-    facts, chunks, usage = await extract_facts_from_text(
-        text=content,
-        event_date=datetime.now(),
-        llm_config=llm_config,
-        agent_name="test-agent",
-        context="Friday Standup meeting",
-        extract_opinions=False,
-    )
-
-    duration = time.time() - start_time
-
-    logger.info(f"\n{'='*60}")
-    logger.info(f"EXTRACTION RESULTS")
-    logger.info(f"{'='*60}")
-    logger.info(f"Duration: {duration:.2f}s")
-    logger.info(f"Chunks: {len(chunks)}")
-    logger.info(f"Facts extracted: {len(facts)}")
-    logger.info(f"Input tokens: {usage.input_tokens}")
-    logger.info(f"Output tokens: {usage.output_tokens}")
-    logger.info(f"Token ratio (out/in): {usage.output_tokens / max(1, usage.input_tokens):.2f}")
-
-    # Analyze facts by type
-    fact_types = {}
-    for fact in facts:
-        ft = fact.fact_type
-        fact_types[ft] = fact_types.get(ft, 0) + 1
-
-    logger.info(f"\nFacts by type:")
-    for ft, count in sorted(fact_types.items()):
-        logger.info(f"  {ft}: {count}")
-
-    # Show sample facts
-    logger.info(f"\nSample facts (first 10):")
-    for i, fact in enumerate(facts[:10]):
-        logger.info(f"\n  [{i+1}] {fact.fact_type}: {fact.fact[:150]}...")
-
-    # Show facts containing key terms
-    key_terms = ["kubernetes", "k8s", "CKA", "certification", "Alice"]
-    logger.info(f"\n{'='*60}")
-    logger.info(f"FACTS CONTAINING KEY TERMS")
-    logger.info(f"{'='*60}")
-
-    for term in key_terms:
-        matching = [f for f in facts if term.lower() in f.fact.lower()]
-        logger.info(f"\n'{term}' ({len(matching)} facts):")
-        for fact in matching[:3]:
-            logger.info(f"  - {fact.fact[:200]}...")
-
-    assert len(facts) > 0, "Should extract at least one fact"
@@ -1,288 +0,0 @@
-"""
-Test suite for fact extraction output size validation.
-
-Ensures that fact extraction doesn't produce excessively verbose output
-relative to input size.
-"""
-
-import json
-from datetime import datetime
-
-import pytest
-
-from hindsight_api import LLMConfig
-from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-
-
-def estimate_tokens(text: str) -> int:
-    """Rough token estimate: ~4 chars per token for English text."""
-    return len(text) // 4
-
-
-class TestFactExtractionOutputRatio:
-    """Tests for output size relative to input."""
-
-    @pytest.mark.asyncio
-    async def test_output_ratio_simple_text(self):
-        """
-        Test that output size is reasonable for simple text.
-
-        The total output (all fact texts combined) should not be excessively
-        larger than the input text.
-        """
-        text = """
-I went to the grocery store yesterday and bought some apples and oranges.
-The weather was really nice, sunny with a light breeze.
-I ran into my neighbor Sarah who mentioned she's planning a trip to Italy next month.
-"""
-
-        context = "Personal diary entry"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2024, 6, 15),
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser"
-        )
-
-        input_length = len(text)
-        output_length = sum(len(f.fact) for f in facts)
-        ratio = output_length / input_length if input_length > 0 else 0
-
-        print(f"\nSimple text test:")
-        print(f"  Input length: {input_length} chars")
-        print(f"  Output length: {output_length} chars")
-        print(f"  Number of facts: {len(facts)}")
-        print(f"  Output/Input ratio: {ratio:.2f}")
-        print(f"  Facts:")
-        for i, f in enumerate(facts):
-            print(f"    [{i}] ({len(f.fact)} chars): {f.fact[:100]}...")
-
-        # Output should not be more than 5x the input
-        assert ratio < 5.0, (
-            f"Output/input ratio {ratio:.2f} is too high! "
-            f"Input: {input_length} chars, Output: {output_length} chars. "
-            f"Facts: {[f.fact for f in facts]}"
-        )
-
-    @pytest.mark.asyncio
-    async def test_output_ratio_conversation(self):
-        """
-        Test output ratio for a typical conversation.
-        """
-        text = """
-User: Hey, I'm looking for a good restaurant for my anniversary dinner.
-Assistant: I'd recommend La Maison for a romantic atmosphere. They have excellent French cuisine.
-User: That sounds great! We love French food. What's the price range?
-Assistant: It's upscale, around $100-150 per person. They also have a great wine selection.
-User: Perfect, I'll make a reservation for Saturday at 7pm.
-"""
-
-        context = "Restaurant recommendation conversation"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2024, 6, 15),
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser"
-        )
-
-        input_length = len(text)
-        output_length = sum(len(f.fact) for f in facts)
-        ratio = output_length / input_length if input_length > 0 else 0
-
-        print(f"\nConversation test:")
-        print(f"  Input length: {input_length} chars")
-        print(f"  Output length: {output_length} chars")
-        print(f"  Number of facts: {len(facts)}")
-        print(f"  Output/Input ratio: {ratio:.2f}")
-        print(f"  Facts:")
-        for i, f in enumerate(facts):
-            print(f"    [{i}] ({len(f.fact)} chars): {f.fact[:100]}...")
-
-        # Output should not be more than 5x the input
-        assert ratio < 5.0, (
-            f"Output/input ratio {ratio:.2f} is too high! "
-            f"Input: {input_length} chars, Output: {output_length} chars"
-        )
-
-    @pytest.mark.asyncio
-    async def test_output_ratio_longer_text(self):
-        """
-        Test output ratio for a longer piece of text.
-        """
-        text = """
-Last weekend was incredible. On Saturday morning, I woke up early and went for a 5-mile run
-through the park near my house. The cherry blossoms were in full bloom, which made the whole
-experience magical. After the run, I met up with my college friend Mike at our favorite cafe
-downtown. We hadn't seen each other in about six months, so we had a lot to catch up on.
-
-Mike told me about his new job at a tech startup in San Francisco. He's working as a senior
-engineer there and seems really excited about the projects they're building. Something about
-AI-powered healthcare solutions. He mentioned they're looking for more engineers and asked if
-I'd be interested in applying. I told him I'd think about it, but honestly, I'm pretty happy
-with my current position.
-
-In the afternoon, we went to see a movie - the new sci-fi thriller that everyone's been talking
-about. I thought it was okay, maybe a 7 out of 10. Mike loved it though. He's always been more
-into action-heavy films than I am.
-
-Sunday was more relaxed. I spent most of the day working on my photography hobby. I've been
-learning to use Lightroom to edit my photos, and I finally feel like I'm getting the hang of it.
-I edited about 20 photos from my recent trip to the mountains.
-"""
-
-        context = "Personal blog post"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2024, 4, 15),
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser"
-        )
-
-        input_length = len(text)
-        output_length = sum(len(f.fact) for f in facts)
-        ratio = output_length / input_length if input_length > 0 else 0
-
-        print(f"\nLonger text test:")
-        print(f"  Input length: {input_length} chars")
-        print(f"  Output length: {output_length} chars")
-        print(f"  Number of facts: {len(facts)}")
-        print(f"  Output/Input ratio: {ratio:.2f}")
-        print(f"  Avg fact length: {output_length / len(facts):.0f} chars" if facts else "N/A")
-        print(f"  Facts:")
-        for i, f in enumerate(facts):
-            print(f"    [{i}] ({len(f.fact)} chars): {f.fact[:100]}...")
-
-        # Output should not be more than 4x the input for longer texts
-        # (ratio should decrease as input grows)
-        assert ratio < 4.0, (
-            f"Output/input ratio {ratio:.2f} is too high! "
-            f"Input: {input_length} chars, Output: {output_length} chars"
-        )
-
-        # Also check that individual facts aren't excessively long
-        max_fact_length = max(len(f.fact) for f in facts) if facts else 0
-        assert max_fact_length < 1000, (
-            f"Individual fact too long: {max_fact_length} chars. "
-            f"Facts should be concise."
-        )
-
-    @pytest.mark.asyncio
-    async def test_token_ratio_with_locomo_conversation(self):
-        """
-        Test output ratio with a realistic locomo conversation.
-
-        The user reported: input_tokens=4714, output_tokens=24824, ratio=5.27
-        This test uses real conversation data to check for excessive output.
-        """
-        import os
-
-        # Load locomo conversation
-        fixture_path = os.path.join(
-            os.path.dirname(__file__),
-            "fixtures",
-            "locomo_conversation_sample.json"
-        )
-        with open(fixture_path, "r") as f:
-            data = json.load(f)
-
-        # Use session_1 (a realistic conversation between Caroline and Melanie)
-        session = data["conversation"]["session_1"]
-
-        # Convert to text format
-        text = "\n".join([f"{turn['speaker']}: {turn['text']}" for turn in session])
-
-        context = f"Conversation between {data['conversation']['speaker_a']} and {data['conversation']['speaker_b']}"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2023, 5, 8),  # Date from locomo dataset
-            context=context,
-            llm_config=llm_config,
-            agent_name=data["conversation"]["speaker_a"]
-        )
-
-        # Calculate ratios
-        input_length = len(text)
-        output_length = sum(len(f.fact) for f in facts)
-        text_to_output_ratio = output_length / input_length if input_length > 0 else 0
-
-        print(f"\nLocomo conversation test:")
-        print(f"  Input text: {input_length} chars (~{input_length // 4} tokens)")
-        print(f"  Output text: {output_length} chars (~{output_length // 4} tokens)")
-        print(f"  Number of facts: {len(facts)}")
-        print(f"  Output/Input text ratio: {text_to_output_ratio:.2f}")
-        print(f"  Sample facts:")
-        for i, f in enumerate(facts[:5]):  # Show first 5
-            print(f"    [{i}] ({len(f.fact)} chars): {f.fact[:80]}...")
-        if len(facts) > 5:
-            print(f"    ... and {len(facts) - 5} more")
-
-        # The output should not be more than 4x the input TEXT
-        # This catches the extreme 5.27x case reported by the user
-        assert text_to_output_ratio < 4.0, (
-            f"Output/input text ratio {text_to_output_ratio:.2f} is too high! "
-            f"Input text: {input_length} chars, Output: {output_length} chars. "
-            f"Number of facts: {len(facts)}"
-        )
-
-        # Sanity check on number of facts
-        # A conversation shouldn't produce an unreasonable number of facts
-        num_turns = len(session)
-        max_expected_facts = num_turns * 2  # At most 2 facts per conversation turn
-
-        assert len(facts) <= max_expected_facts, (
-            f"Too many facts: {len(facts)} for {num_turns} conversation turns. "
-            f"Expected at most {max_expected_facts}."
-        )
-
-    @pytest.mark.asyncio
-    async def test_number_of_facts_reasonable(self):
-        """
-        Test that the number of extracted facts is reasonable.
-
-        We shouldn't extract way more facts than there are sentences/statements
-        in the input.
-        """
-        text = """
-I love coffee in the morning.
-My favorite restaurant is Olive Garden.
-I work as a software engineer at Google.
-My dog's name is Max.
-I'm planning to visit Japan next year.
-"""
-
-        context = "Personal info"
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2024, 6, 15),
-            context=context,
-            llm_config=llm_config,
-            agent_name="TestUser"
-        )
-
-        # Count approximate number of statements (sentences)
-        num_statements = len([s for s in text.split('.') if s.strip()])
-
-        print(f"\nNumber of facts test:")
-        print(f"  Input statements: ~{num_statements}")
-        print(f"  Extracted facts: {len(facts)}")
-        print(f"  Facts:")
-        for i, f in enumerate(facts):
-            print(f"    [{i}]: {f.fact[:80]}...")
-
-        # Should not extract more than 2x the number of input statements
-        assert len(facts) <= num_statements * 2, (
-            f"Too many facts extracted: {len(facts)} for ~{num_statements} input statements"
-        )
@@ -43,7 +43,7 @@ Marcus felt anxious about the upcoming interview.
        context = "Personal journal entry"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -75,7 +75,7 @@ The music was so loud I could barely hear myself think.
        context = "Personal experience"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -108,7 +108,7 @@ Maybe we should reconsider the timeline.
        context = "Team discussion"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -141,7 +141,7 @@ I'm unable to attend the conference due to scheduling conflicts.
        context = "Personal profile discussion"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -173,7 +173,7 @@ Unlike last year, we're ahead of schedule.
        context = "Project review"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -206,7 +206,7 @@ She's enthusiastic about the opportunity.
        context = "Team meeting"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -239,7 +239,7 @@ I'm planning to switch careers because I'm not fulfilled in my current role.
        context = "Personal goals discussion"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -276,7 +276,7 @@ Family is the most important thing to her.
        context = "Personal values discussion"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -310,7 +310,7 @@ I prefer presenting in person rather than virtually because I can read the room

        event_date = datetime(2024, 11, 13)

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=event_date,
            context=context,
@@ -354,7 +354,6 @@ class TestTemporalConversion:
        Test that relative temporal expressions are converted to absolute dates.

        Critical: "yesterday" should become "on November 12, 2024", NOT "recently"
-        LLM behavior may vary, so we check the occurred_start field rather than fact text.
        """
        text = """
 Yesterday I went for a morning jog for the first time in a nearby park.
@@ -367,7 +366,7 @@ I'm planning to visit Tokyo next month.

        event_date = datetime(2024, 11, 13)

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=event_date,
            context=context,
@@ -380,18 +379,20 @@ I'm planning to visit Tokyo next month.
        all_facts_text = " ".join([f.fact.lower() for f in facts])

        # Should NOT contain vague temporal terms
-        prohibited_terms = ["recently", "lately", "a while ago", "some time ago"]
+        prohibited_terms = ["recently", "soon", "lately", "a while ago", "some time ago"]
        found_prohibited = [term for term in prohibited_terms if term in all_facts_text]

        assert len(found_prohibited) == 0, (
            f"Should NOT use vague temporal terms. Found: {found_prohibited}"
        )

-        # Check that at least one fact has a valid occurred_start date
-        facts_with_temporal = [f for f in facts if f.occurred_start]
-        assert len(facts_with_temporal) >= 1, (
-            f"At least one fact should have temporal data (occurred_start). "
-            f"Facts: {[f.fact for f in facts]}"
+        # Should contain specific date references
+        temporal_indicators = ["november", "12", "early november", "week of", "december"]
+        found_temporal = [term for term in temporal_indicators if term in all_facts_text]
+
+        assert len(found_temporal) >= 1, (
+            f"Should convert relative dates to absolute. "
+            f"Found: {found_temporal}, Expected month/date references"
        )

    @pytest.mark.asyncio
@@ -418,7 +419,7 @@ with a concert surrounded by music, joy and the warm summer breeze.

        for attempt in range(max_retries):
            try:
-                facts, _, _ = await extract_facts_from_text(
+                facts, _ = await extract_facts_from_text(
                    text=text,
                    event_date=event_date,
                    context=context,
@@ -480,7 +481,6 @@ with a concert surrounded by music, joy and the warm summer breeze.
        """Test that the date field is calculated correctly for "yesterday" events."""
        text = """
 Yesterday I went for a morning jog for the first time in a nearby park.
-It was a beautiful day and I plan to make this a regular habit.
 """

        context = "Personal diary"
@@ -488,7 +488,7 @@ It was a beautiful day and I plan to make this a regular habit.

        event_date = datetime(2024, 11, 13)

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=event_date,
            context=context,
@@ -498,30 +498,25 @@ It was a beautiful day and I plan to make this a regular habit.

        assert len(facts) > 0, "Should extract at least one fact"

-        # Find a fact with occurred_start
-        facts_with_date = [f for f in facts if f.occurred_start]
+        jogging_fact = facts[0]

-        # If we got a fact with temporal data, verify the date is reasonable
-        if facts_with_date:
-            jogging_fact = facts_with_date[0]
-            fact_date_str = jogging_fact.occurred_start
-            if 'T' in fact_date_str:
-                fact_date = datetime.fromisoformat(fact_date_str.replace('Z', '+00:00'))
-            else:
-                fact_date = datetime.fromisoformat(fact_date_str)
+        fact_date_str = jogging_fact.occurred_start
+        if 'T' in fact_date_str:
+            fact_date = datetime.fromisoformat(fact_date_str.replace('Z', '+00:00'))
+        else:
+            fact_date = datetime.fromisoformat(fact_date_str)

-            assert fact_date.year == 2024, "Year should be 2024"
-            assert fact_date.month == 11, "Month should be November"
-            # Accept day 12 (ideal: yesterday) or 13 (conversation date) as valid
-            assert fact_date.day in (12, 13), (
-                f"Day should be 12 or 13 (around Nov 13 event), but got {fact_date.day}."
-            )
+        assert fact_date.year == 2024, "Year should be 2024"
+        assert fact_date.month == 11, "Month should be November"
+        # Accept day 12 (ideal: yesterday) or 13 (conversation date) as valid
+        assert fact_date.day in (12, 13), (
+            f"Day should be 12 or 13 (around Nov 13 event), but got {fact_date.day}."
+        )

        all_facts_text = " ".join([f.fact.lower() for f in facts])

-        # The content should be preserved in some form
-        assert any(term in all_facts_text for term in ["jog", "morning", "park", "first"]), \
-            f"Should preserve key content. Facts: {[f.fact for f in facts]}"
+        assert "first time" in all_facts_text or "first" in all_facts_text, \
+            "Should preserve 'first time' qualifier"

        assert "recently" not in all_facts_text, \
            "Should NOT convert 'yesterday' to 'recently'"
@@ -542,7 +537,7 @@ It was a beautiful day and I plan to make this a regular habit.
        This morning I had coffee with Alice.
        """

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=reference_date,
            llm_config=llm_config,
@@ -572,7 +567,7 @@ It was a beautiful day and I plan to make this a regular habit.

        text = "Alice works at Google. She loves Python programming."

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=reference_date,
            llm_config=llm_config,
@@ -599,7 +594,7 @@ It was a beautiful day and I plan to make this a regular habit.
        Bob will start his vacation on April 1st.
        """

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=reference_date,
            llm_config=llm_config,
@@ -650,7 +645,7 @@ great time! Every time I see it, I can't help but smile.

        event_date = datetime(2023, 2, 23)

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=event_date,
            context=context,
@@ -700,7 +695,7 @@ I've learned so much from it.
        context = "Personal update"
        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            context=context,
@@ -718,21 +713,15 @@ I've learned so much from it.
        assert has_project, "Should mention the project"
        assert has_qualities, "Should mention the qualities/learning"

-        # Check that pronouns are resolved - either:
-        # 1. "project" appears with characteristics in same fact, OR
-        # 2. "project" is explicitly mentioned in multiple facts (showing pronoun resolution)
-        # The key is that "it" should be resolved to "project" rather than left as ambiguous
-        project_facts = [f for f in facts if "project" in f.fact.lower()]
+        connected_fact_found = False
+        for fact in facts:
+            fact_text = fact.fact.lower()
+            if "project" in fact_text and any(word in fact_text for word in ["challenging", "rewarding"]):
+                connected_fact_found = True
+                break

-        # If we have multiple facts mentioning project, pronoun resolution worked
-        # (the LLM connected "it" back to "project" in subsequent facts)
-        pronoun_resolved = len(project_facts) >= 2 or any(
-            "project" in f.fact.lower() and any(word in f.fact.lower() for word in ["challenging", "rewarding", "learned"])
-            for f in facts
-        )
-
-        assert pronoun_resolved, (
-            "Should resolve 'it' to 'the project' - either in combined facts or by mentioning project in multiple facts. "
+        assert connected_fact_found, (
+            "Should resolve 'it' to 'the project' and connect characteristics in the same fact. "
            f"Facts: {[f.fact for f in facts]}"
        )

@@ -769,7 +758,7 @@ Jamie: Congratulations! I'd love to read it.

        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=transcript,
            event_date=datetime(2024, 11, 13),
            llm_config=llm_config,
@@ -814,7 +803,7 @@ We presented our findings to the team yesterday.

        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=text,
            event_date=datetime(2024, 11, 13),
            llm_config=llm_config,
@@ -849,7 +838,7 @@ Jamie: [teasing] We'll see who's right, my Niners pick is solid.

        llm_config = LLMConfig.for_memory()

-        facts, _, _ = await extract_facts_from_text(
+        facts, _ = await extract_facts_from_text(
            text=transcript,
            event_date=datetime(2024, 11, 14),
            context=context,
@@ -883,8 +872,6 @@ Jamie: [teasing] We'll see who's right, my Niners pick is solid.

        This addresses the issue where podcast outros like "that's all for today,
        don't forget to subscribe" were being extracted as facts.
-
-        Note: LLM fact extraction is non-deterministic, so we retry up to 3 times.
        """

        transcript = """
@@ -910,40 +897,194 @@ so the algorithm learns to box out. See you next week!

        llm_config = LLMConfig.for_memory()

-        max_retries = 3
-        last_error = None
+        facts, _ = await extract_facts_from_text(
+            text=transcript,
+            event_date=datetime(2024, 11, 13),
+            llm_config=llm_config,
+            agent_name="Marcus",
+            context=context
+        )

-        for attempt in range(max_retries):
-            try:
-                facts, _, _ = await extract_facts_from_text(
-                    text=transcript,
-                    event_date=datetime(2024, 11, 13),
-                    llm_config=llm_config,
-                    agent_name="Marcus",
-                    context=context
-                )
+        assert len(facts) > 0, "Should extract at least one fact"

-                assert len(facts) > 0, "Should extract at least one fact"
+        # The main goal is to extract substantive content about AI research
+        # Meta-commentary filtering is ideal but not strictly required
+        all_facts_text = " ".join([f.fact.lower() for f in facts])

-                # The main goal is to extract substantive content about AI research
-                # Meta-commentary filtering is ideal but not strictly required
-                all_facts_text = " ".join([f.fact.lower() for f in facts])
-
-                # Should extract the actual AI research content
-                has_substantive_content = any(term in all_facts_text for term in [
-                    "interpretability", "ai", "safety", "research", "models", "decisions"
-                ])
-                assert has_substantive_content, \
-                    f"Should extract substantive AI research content. Facts: {[f.fact for f in facts]}"
-
-                return  # Test passed
-
-            except AssertionError as e:
-                last_error = e
-                if attempt < max_retries - 1:
-                    print(f"Test attempt {attempt + 1} failed: {e}. Retrying...")
-                    continue
-                else:
-                    raise e
+        # Should extract the actual AI research content
+        has_substantive_content = any(term in all_facts_text for term in [
+            "interpretability", "ai", "safety", "research", "models", "decisions"
+        ])
+        assert has_substantive_content, \
+            f"Should extract substantive AI research content. Facts: {[f.fact for f in facts]}"


+# =============================================================================
+# DISPOSITION INFERENCE TESTS
+# =============================================================================
+
+class TestDispositionInference:
+    """Tests for LLM-based disposition trait inference from background."""
+
+    @pytest.mark.asyncio
+    async def test_background_merge_with_disposition_inference(self, memory, request_context):
+        """Test that background merge infers disposition traits by default."""
+        import uuid
+        bank_id = f"test_infer_{uuid.uuid4().hex[:8]}"
+
+        result = await memory.merge_bank_background(
+            bank_id,
+            "I am a creative software engineer who loves innovation and trying new technologies",
+            update_disposition=True,
+            request_context=request_context,
+        )
+
+        assert "background" in result
+        assert "disposition" in result
+
+        background = result["background"]
+        disposition = result["disposition"]
+
+        assert "creative" in background.lower() or "innovation" in background.lower()
+
+        # Check that new traits are present with valid values (1-5)
+        required_traits = ["skepticism", "literalism", "empathy"]
+        for trait in required_traits:
+            assert trait in disposition
+            assert 1 <= disposition[trait] <= 5
+
+    @pytest.mark.asyncio
+    async def test_background_merge_without_disposition_inference(self, memory, request_context):
+        """Test that background merge skips disposition inference when disabled."""
+        import uuid
+        bank_id = f"test_no_infer_{uuid.uuid4().hex[:8]}"
+
+        initial_profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+        initial_disposition = initial_profile["disposition"]
+
+        result = await memory.merge_bank_background(
+            bank_id,
+            "I am a data scientist",
+            update_disposition=False,
+            request_context=request_context,
+        )
+
+        assert "background" in result
+        assert "disposition" not in result
+
+        final_profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+        final_disposition = final_profile["disposition"]
+
+        assert initial_disposition == final_disposition
+
+    @pytest.mark.asyncio
+    async def test_disposition_inference_for_lawyer(self, memory, request_context):
+        """Test disposition inference for lawyer profile (high skepticism, high literalism)."""
+        import uuid
+        bank_id = f"test_lawyer_{uuid.uuid4().hex[:8]}"
+
+        result = await memory.merge_bank_background(
+            bank_id,
+            "I am a lawyer who focuses on contract details and never takes claims at face value",
+            update_disposition=True,
+            request_context=request_context,
+        )
+
+        disposition = result["disposition"]
+
+        # Lawyers should have higher skepticism and literalism
+        assert disposition["skepticism"] >= 3
+        assert disposition["literalism"] >= 3
+
+    @pytest.mark.asyncio
+    async def test_disposition_inference_for_therapist(self, memory, request_context):
+        """Test disposition inference for therapist profile (high empathy)."""
+        import uuid
+        bank_id = f"test_therapist_{uuid.uuid4().hex[:8]}"
+
+        result = await memory.merge_bank_background(
+            bank_id,
+            "I am a therapist who deeply understands and connects with people's emotional struggles",
+            update_disposition=True,
+            request_context=request_context,
+        )
+
+        disposition = result["disposition"]
+
+        # Therapists should have higher empathy
+        assert disposition["empathy"] >= 3
+
+    @pytest.mark.asyncio
+    async def test_disposition_updates_in_database(self, memory, request_context):
+        """Test that inferred disposition is actually stored in database."""
+        import uuid
+        bank_id = f"test_db_update_{uuid.uuid4().hex[:8]}"
+
+        result = await memory.merge_bank_background(
+            bank_id,
+            "I am an innovative designer",
+            update_disposition=True,
+            request_context=request_context,
+        )
+
+        inferred_disposition = result["disposition"]
+
+        profile = await memory.get_bank_profile(bank_id, request_context=request_context)
+        db_disposition = profile["disposition"]
+
+        # Compare values (db_disposition is a Pydantic model)
+        assert db_disposition.skepticism == inferred_disposition["skepticism"]
+        assert db_disposition.literalism == inferred_disposition["literalism"]
+        assert db_disposition.empathy == inferred_disposition["empathy"]
+
+    @pytest.mark.asyncio
+    async def test_multiple_background_merges_update_disposition(self, memory, request_context):
+        """Test that each background merge can update disposition."""
+        import uuid
+        bank_id = f"test_multi_merge_{uuid.uuid4().hex[:8]}"
+
+        result1 = await memory.merge_bank_background(
+            bank_id,
+            "I am a software engineer",
+            update_disposition=True,
+            request_context=request_context,
+        )
+        disposition1 = result1["disposition"]
+
+        result2 = await memory.merge_bank_background(
+            bank_id,
+            "I love creative problem solving and innovation",
+            update_disposition=True,
+            request_context=request_context,
+        )
+        disposition2 = result2["disposition"]
+
+        assert "engineer" in result2["background"].lower() or "software" in result2["background"].lower()
+        assert "creative" in result2["background"].lower() or "innovation" in result2["background"].lower()
+
+    @pytest.mark.asyncio
+    async def test_background_merge_conflict_resolution_with_disposition(self, memory, request_context):
+        """Test that conflicts are resolved and disposition reflects final background."""
+        import uuid
+        bank_id = f"test_conflict_{uuid.uuid4().hex[:8]}"
+
+        await memory.merge_bank_background(
+            bank_id,
+            "I was born in Colorado and prefer stability",
+            update_disposition=True,
+            request_context=request_context,
+        )
+
+        result = await memory.merge_bank_background(
+            bank_id,
+            "You were born in Texas and are very skeptical of people",
+            update_disposition=True,
+            request_context=request_context,
+        )
+
+        background = result["background"]
+        disposition = result["disposition"]
+
+        assert "texas" in background.lower()
+        # Higher skepticism expected from "very skeptical of people"
+        assert disposition["skepticism"] >= 3
@@ -51,7 +51,7 @@ Marcus: Yeah, I realized I was being too optimistic about their defense.
    results = await memory.recall_async(
        bank_id=bank_id,
        query="Marcus prediction Rams",
-        fact_type=['experience', 'world'],
+        fact_type=['opinion', 'experience', 'world'],
        budget=Budget.LOW,
        max_tokens=8192,
        request_context=request_context,
@@ -61,8 +61,8 @@ Marcus: Yeah, I realized I was being too optimistic about their defense.
    for i, result in enumerate(results.results):
        print(f"{i+1}. [{result.mentioned_at}] {result.text[:100]}")

-    # Get all facts (Marcus's predictions/statements)
-    agent_facts = results.results
+    # Get all opinion facts (Marcus's predictions/statements)
+    agent_facts = [r for r in results.results if r.fact_type == 'opinion']

    print(f"\n=== Agent facts (Marcus's statements) ===")
    for i, fact in enumerate(agent_facts):
@@ -70,7 +70,6 @@ Marcus: Yeah, I realized I was being too optimistic about their defense.

    # Check that agent facts have different timestamps
    if len(agent_facts) >= 2:
-        # Parse timestamps
        timestamps = [datetime.fromisoformat(f.mentioned_at.replace('Z', '+00:00')) for f in agent_facts]

        # Verify timestamps are different (have time offsets)
@@ -78,40 +77,42 @@ Marcus: Yeah, I realized I was being too optimistic about their defense.
        assert len(unique_timestamps) == len(timestamps), \
            f"Expected unique timestamps for each fact, but got duplicates: {timestamps}"

-        # Sort facts by timestamp for ordering check
-        # Note: recall returns by relevance, not time order
-        sorted_facts = sorted(agent_facts, key=lambda f: datetime.fromisoformat(f.mentioned_at.replace('Z', '+00:00')))
-        sorted_timestamps = [datetime.fromisoformat(f.mentioned_at.replace('Z', '+00:00')) for f in sorted_facts]
-
-        # Verify sorted timestamps are in ascending order
-        for i in range(len(sorted_timestamps) - 1):
-            assert sorted_timestamps[i] < sorted_timestamps[i + 1], \
-                f"Facts should have sequential timestamps. Fact {i} ({sorted_timestamps[i]}) >= Fact {i+1} ({sorted_timestamps[i+1]})"
+        # Verify timestamps are in order (ascending)
+        for i in range(len(timestamps) - 1):
+            assert timestamps[i] < timestamps[i + 1], \
+                f"Facts should be ordered by time. Fact {i} ({timestamps[i]}) >= Fact {i+1} ({timestamps[i+1]})"

        # Verify reasonable time spacing (should be ~10 seconds apart)
-        time_diffs = [(sorted_timestamps[i+1] - sorted_timestamps[i]).total_seconds() for i in range(len(sorted_timestamps) - 1)]
+        time_diffs = [(timestamps[i+1] - timestamps[i]).total_seconds() for i in range(len(timestamps) - 1)]
        print(f"\n=== Time differences between facts: {time_diffs} seconds ===")

        # Each fact should be 10+ seconds apart (allowing for some flexibility)
        for diff in time_diffs:
            assert diff >= 5, f"Expected at least 5 seconds between facts, got {diff}"

-        # Update agent_facts to be sorted for subsequent checks
-        agent_facts = sorted_facts
-        timestamps = sorted_timestamps
-
        print(f"\n✅ All {len(agent_facts)} agent facts have properly ordered timestamps")

-    # Verify that facts capture the key information
-    # Note: LLM may merge related predictions into single facts
+    # Verify that retrieval returns facts in chronological order
+    # The first prediction should come before the changed prediction
    agent_texts = [f.text.lower() for f in agent_facts]
-    all_text = " ".join(agent_texts)

-    # Look for evidence of the predictions being captured (may be merged or separate)
-    has_prediction_info = '27' in all_text or 'rams' in all_text or 'prediction' in all_text
+    # Look for evidence of the sequence
+    has_first_prediction = any('27' in text and '24' in text for text in agent_texts)
+    has_changed_prediction = any('chang' in text or 'by 3' in text or 'realized' in text for text in agent_texts)

-    assert has_prediction_info, "Facts should contain information about Marcus's predictions"
-    print(f"\n✅ Facts capture prediction information")
+    if has_first_prediction and has_changed_prediction:
+        # Find indices
+        first_idx = next(i for i, text in enumerate(agent_texts) if '27' in text and '24' in text)
+        changed_idx = next(i for i, text in enumerate(agent_texts) if 'chang' in text or 'by 3' in text or 'realized' in text)
+
+        print(f"\nFirst prediction at index {first_idx}: {agent_facts[first_idx].text[:100]}")
+        print(f"Changed prediction at index {changed_idx}: {agent_facts[changed_idx].text[:100]}")
+
+        # The original prediction should come before the changed one
+        assert timestamps[first_idx] < timestamps[changed_idx], \
+            "Original prediction should have earlier timestamp than changed prediction"
+
+        print(f"\n✅ Temporal ordering preserved: First prediction came before changed prediction")

    # Cleanup
    await memory.delete_bank(bank_id, request_context=request_context)
@@ -155,14 +156,14 @@ Alice: I reconsidered the team's experience level.
    results = await memory.recall_async(
        bank_id=bank_id,
        query="Alice preference React Vue",
-        fact_type=['experience', 'world'],
+        fact_type=['opinion', 'experience'],
        budget=Budget.LOW,
        max_tokens=8192,
        request_context=request_context,
    )

    print(f"\n=== Retrieved {len(results.results)} agent facts ===")
-    agent_facts = results.results
+    agent_facts = [r for r in results.results if r.fact_type in ('opinion', 'experience')]

    for i, fact in enumerate(agent_facts):
        print(f"{i+1}. [{fact.mentioned_at}] {fact.text[:80]}")
@@ -60,6 +60,17 @@ async def test_full_api_workflow(api_client, test_bank_id):
    assert response.status_code == 200
    profile = response.json()
    assert "disposition" in profile
+    assert "background" in profile
+
+    # Add background
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/background",
+        json={
+            "content": "A software engineer passionate about AI and memory systems."
+        }
+    )
+    assert response.status_code == 200
+    assert "software engineer" in response.json()["background"].lower()

    # ================================================================
    # 2. Memory Storage
@@ -233,42 +244,17 @@ async def test_full_api_workflow(api_client, test_bank_id):
    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
    assert response.status_code == 200
    updated_profile = response.json()
-    assert updated_profile["disposition"]["skepticism"] == 4
-    assert updated_profile["disposition"]["literalism"] == 3
-    assert updated_profile["disposition"]["empathy"] == 4
+    assert "software engineer" in updated_profile["background"].lower()

    # ================================================================
    # 8. Test Entity Endpoints
    # ================================================================

-    # List entities with pagination
+    # List entities
    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/entities")
    assert response.status_code == 200
    entities_data = response.json()
    assert "items" in entities_data
-    assert "total" in entities_data
-    assert "limit" in entities_data
-    assert "offset" in entities_data
-    assert entities_data["offset"] == 0
-    assert entities_data["limit"] == 100  # default limit
-
-    # Test pagination with custom limit and offset
-    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/entities?limit=5&offset=0")
-    assert response.status_code == 200
-    paginated_data = response.json()
-    assert paginated_data["limit"] == 5
-    assert paginated_data["offset"] == 0
-    assert len(paginated_data["items"]) <= 5
-
-    # Test offset
-    if entities_data["total"] > 1:
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/entities?limit=1&offset=1")
-        assert response.status_code == 200
-        offset_data = response.json()
-        assert offset_data["offset"] == 1
-        # With offset=1, we should get different entity than first one (if there are multiple)
-        if len(offset_data["items"]) > 0 and len(entities_data["items"]) > 1:
-            assert offset_data["items"][0]["id"] != entities_data["items"][0]["id"]

    # Get specific entity if any exist
    if len(entities_data['items']) > 0:
@@ -280,11 +266,11 @@ async def test_full_api_workflow(api_client, test_bank_id):
        entity_detail = response.json()
        assert "id" in entity_detail

-        # Test regenerate observations (deprecated - returns 410 Gone)
+        # Test regenerate observations
        response = await api_client.post(
            f"/v1/default/banks/{test_bank_id}/entities/{entity_id}/regenerate"
        )
-        assert response.status_code == 410  # Deprecated endpoint
+        assert response.status_code == 200

    # ================================================================
    # 9. List All Banks (should include our test bank)
@@ -302,9 +288,8 @@ async def test_full_api_workflow(api_client, test_bank_id):
    # 10. Clean Up
    # ================================================================

-    # Clean up the test bank (delete bank endpoint is tested separately)
-    response = await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-    assert response.status_code == 200
+    # Note: No delete bank endpoint in API, so test data remains in DB
+    # Using timestamped bank IDs prevents conflicts between test runs


@pytest.mark.asyncio
@@ -503,87 +488,6 @@ async def test_document_deletion_with_slashes_in_id(api_client):
        await api_client.delete(f"/v1/default/banks/{test_bank_id}")


-@pytest.mark.asyncio
-async def test_delete_bank(api_client):
-    """Test delete bank endpoint.
-
-    Workflow:
-    1. Create a bank by storing memories
-    2. Verify bank exists with data
-    3. Delete the bank
-    4. Verify bank and all data is deleted
-    """
-    test_bank_id = f"delete_bank_test_{datetime.now().timestamp()}"
-
-    # 1. Create bank by storing memories with a document
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "Alice is a software engineer at TechCorp.",
-                    "context": "team info",
-                    "document_id": "team-doc-1",
-                },
-                {
-                    "content": "Bob is the CTO and leads the engineering team.",
-                    "context": "team info",
-                    "document_id": "team-doc-1",
-                },
-            ]
-        },
-    )
-    assert response.status_code == 200
-    assert response.json()["success"] is True
-
-    # 2. Verify bank exists with data
-    # Check profile
-    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
-    assert response.status_code == 200
-
-    # Check stats show data exists
-    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/stats")
-    assert response.status_code == 200
-    stats = response.json()
-    assert stats["total_nodes"] > 0
-
-    # Check documents exist
-    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/documents")
-    assert response.status_code == 200
-    assert len(response.json()["items"]) > 0
-
-    # Check bank is in list
-    response = await api_client.get("/v1/default/banks")
-    assert response.status_code == 200
-    bank_ids = [b["bank_id"] for b in response.json()["banks"]]
-    assert test_bank_id in bank_ids
-
-    # 3. Delete the bank
-    response = await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-    assert response.status_code == 200
-    delete_result = response.json()
-    assert delete_result["success"] is True
-    assert delete_result["deleted_count"] > 0
-    assert "deleted successfully" in delete_result["message"]
-
-    # 4. Verify bank and all data is deleted
-    # Bank should not be in list
-    response = await api_client.get("/v1/default/banks")
-    assert response.status_code == 200
-    bank_ids = [b["bank_id"] for b in response.json()["banks"]]
-    assert test_bank_id not in bank_ids
-
-    # Stats should show zero data (profile auto-creates empty bank)
-    response = await api_client.get(f"/v1/default/banks/{test_bank_id}/stats")
-    assert response.status_code == 200
-    stats = response.json()
-    assert stats["total_nodes"] == 0
-    assert stats["total_documents"] == 0
-
-    # Clean up the auto-created empty bank
-    await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-
-
@pytest.mark.asyncio
 async def test_async_retain(api_client):
    """Test asynchronous retain functionality.
@@ -677,14 +581,11 @@ async def test_async_retain_parallel(api_client):
    test_bank_id = f"async_parallel_test_{datetime.now().timestamp()}"
    num_documents = 5

-    # Prepare multiple documents to retain with realistic names
-    # Using realistic names instead of generic Person0, Company0 to ensure LLM extracts facts
-    people = ["Alice Smith", "Bob Johnson", "Carol Williams", "David Brown", "Emily Davis"]
-    companies = ["TechCorp", "DataSoft", "CloudBase", "NetWorks", "InfoSys"]
+    # Prepare multiple documents to retain
    documents = [
        {
-            "content": f"{people[i]} is a software engineer who works at {companies[i]} and specializes in Python development.",
-            "context": f"employee profile {i}",
+            "content": f"Document {i}: This is test content about Person{i} who works at Company{i}.",
+            "context": f"test document {i}",
            "document_id": f"doc_{i}"
        }
        for i in range(num_documents)
@@ -836,8 +737,9 @@ async def test_reflect_structured_output(api_client):
    assert response.status_code == 200
    result = response.json()

-    # Verify text field exists (may contain text even with structured output)
+    # Verify text field exists (empty when using structured output)
    assert "text" in result
+    assert result["text"] == ""

    # Verify structured output exists and has expected structure
    assert "structured_output" in result
@@ -930,138 +832,3 @@ async def test_reflect_with_max_tokens(api_client):
    # Verify response has text
    assert "text" in result
    assert len(result["text"]) > 0
-
-
-@pytest.mark.asyncio
-async def test_reflect_returns_token_usage(api_client):
-    """Test that reflect endpoint returns token usage metrics.
-
-    The usage field should contain input_tokens, output_tokens, and total_tokens
-    from the LLM call made during reflection.
-    """
-    test_bank_id = f"reflect_usage_test_{datetime.now().timestamp()}"
-
-    # Store a memory to reflect on
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "The capital of France is Paris.",
-                    "context": "geography"
-                }
-            ]
-        }
-    )
-    assert response.status_code == 200
-
-    # Call reflect
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/reflect",
-        json={
-            "query": "What is the capital of France?"
-        }
-    )
-    assert response.status_code == 200
-    result = response.json()
-
-    # Verify response has text
-    assert "text" in result
-    assert len(result["text"]) > 0
-
-    # Verify usage field exists (may be None for agentic reflect which makes multiple LLM calls)
-    assert "usage" in result, "Response should include 'usage' field"
-    usage = result["usage"]
-
-    # Usage is optional - agentic reflect doesn't aggregate multiple LLM call usages
-    if usage is not None:
-        assert "input_tokens" in usage, "Usage should have 'input_tokens'"
-        assert "output_tokens" in usage, "Usage should have 'output_tokens'"
-        assert "total_tokens" in usage, "Usage should have 'total_tokens'"
-
-        # Verify token counts are valid
-        assert usage["input_tokens"] > 0, f"Expected input_tokens > 0, got {usage['input_tokens']}"
-        assert usage["output_tokens"] >= 0, f"Expected output_tokens >= 0, got {usage['output_tokens']}"
-        assert usage["total_tokens"] == usage["input_tokens"] + usage["output_tokens"]
-
-        print(f"Reflect token usage: input={usage['input_tokens']}, output={usage['output_tokens']}, total={usage['total_tokens']}")
-    else:
-        print("Reflect usage is None (expected for agentic reflect)")
-
-
-@pytest.mark.asyncio
-async def test_retain_returns_token_usage(api_client):
-    """Test that retain endpoint returns token usage metrics for synchronous operations.
-
-    The usage field should contain input_tokens, output_tokens, and total_tokens
-    from the LLM calls made during fact extraction.
-    """
-    test_bank_id = f"retain_usage_test_{datetime.now().timestamp()}"
-
-    # Store memory synchronously (async=false is default)
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "items": [
-                {
-                    "content": "Alice is a software engineer at TechCorp. She specializes in machine learning.",
-                    "context": "team introduction"
-                }
-            ]
-        }
-    )
-    assert response.status_code == 200
-    result = response.json()
-
-    # Verify basic response
-    assert result["success"] is True
-    assert result["items_count"] == 1
-    assert result["async"] is False
-
-    # Verify usage field exists and has expected structure
-    assert "usage" in result, "Response should include 'usage' field"
-    usage = result["usage"]
-    assert usage is not None, "Usage should not be None for synchronous retain"
-    assert "input_tokens" in usage, "Usage should have 'input_tokens'"
-    assert "output_tokens" in usage, "Usage should have 'output_tokens'"
-    assert "total_tokens" in usage, "Usage should have 'total_tokens'"
-
-    # Verify token counts are valid
-    assert usage["input_tokens"] > 0, f"Expected input_tokens > 0, got {usage['input_tokens']}"
-    assert usage["output_tokens"] >= 0, f"Expected output_tokens >= 0, got {usage['output_tokens']}"
-    assert usage["total_tokens"] == usage["input_tokens"] + usage["output_tokens"]
-
-    print(f"Retain token usage: input={usage['input_tokens']}, output={usage['output_tokens']}, total={usage['total_tokens']}")
-
-
-@pytest.mark.asyncio
-async def test_retain_async_no_usage(api_client):
-    """Test that async retain does not return usage (as it's processed in background).
-
-    When async=true, the usage field should be None since the actual
-    fact extraction happens asynchronously.
-    """
-    test_bank_id = f"retain_async_no_usage_test_{datetime.now().timestamp()}"
-
-    # Store memory asynchronously
-    response = await api_client.post(
-        f"/v1/default/banks/{test_bank_id}/memories",
-        json={
-            "async": True,
-            "items": [
-                {
-                    "content": "Bob is a data scientist.",
-                    "context": "team introduction"
-                }
-            ]
-        }
-    )
-    assert response.status_code == 200
-    result = response.json()
-
-    # Verify async response
-    assert result["success"] is True
-    assert result["async"] is True
-
-    # Usage should be None for async operations
-    assert result.get("usage") is None, "Async retain should not include usage"
@@ -1,245 +0,0 @@
-"""
-Test that LLM calls record token metrics via the metrics collector.
-"""
-import os
-from unittest.mock import MagicMock, patch
-import pytest
-from hindsight_api.engine.llm_wrapper import LLMProvider
-from hindsight_api.metrics import (
-    MetricsCollector,
-    NoOpMetricsCollector,
-    get_metrics_collector,
-)
-
-
-def get_groq_api_key() -> str | None:
-    """Get Groq API key from environment."""
-    return os.getenv("GROQ_API_KEY")
-
-
-@pytest.mark.asyncio
-async def test_llm_metrics_recorded_for_groq():
-    """
-    Test that LLM metrics are recorded when making LLM calls via Groq.
-    Uses openai/gpt-oss-20b as recommended by Hindsight.
-    """
-    api_key = get_groq_api_key()
-    if not api_key:
-        pytest.skip("Skipping: GROQ_API_KEY not set")
-
-    # Create a mock metrics collector to track record_llm_call calls
-    mock_collector = MagicMock(spec=MetricsCollector)
-
-    with patch("hindsight_api.engine.llm_wrapper.get_metrics_collector", return_value=mock_collector):
-        llm = LLMProvider(
-            provider="groq",
-            api_key=api_key,
-            base_url="",
-            model="openai/gpt-oss-20b",
-        )
-
-        # Make an LLM call with clear instruction
-        response = await llm.call(
-            messages=[
-                {"role": "system", "content": "You are a helpful assistant. Always respond."},
-                {"role": "user", "content": "What is 2+2? Reply with just the number."}
-            ],
-            max_completion_tokens=50,
-            scope="test_metrics",
-        )
-
-        # Verify record_llm_call was called - this is the main test
-        assert mock_collector.record_llm_call.called, "record_llm_call should have been called"
-
-        # Get the call arguments
-        call_kwargs = mock_collector.record_llm_call.call_args.kwargs
-
-        # Verify the call had correct structure
-        assert call_kwargs["provider"] == "groq", f"Expected provider='groq', got {call_kwargs}"
-        assert call_kwargs["model"] == "openai/gpt-oss-20b", f"Expected model='openai/gpt-oss-20b', got {call_kwargs}"
-        assert call_kwargs["scope"] == "test_metrics", f"Expected scope='test_metrics', got {call_kwargs}"
-        assert call_kwargs["duration"] > 0, f"Expected duration > 0, got {call_kwargs['duration']}"
-        assert call_kwargs["input_tokens"] > 0, f"Expected input_tokens > 0, got {call_kwargs['input_tokens']}"
-        assert call_kwargs["output_tokens"] >= 0, f"Expected output_tokens >= 0, got {call_kwargs['output_tokens']}"
-        assert call_kwargs["success"] is True, f"Expected success=True, got {call_kwargs['success']}"
-
-        print(f"\nLLM metrics recorded:")
-        print(f"  provider: {call_kwargs['provider']}")
-        print(f"  model: {call_kwargs['model']}")
-        print(f"  scope: {call_kwargs['scope']}")
-        print(f"  duration: {call_kwargs['duration']:.3f}s")
-        print(f"  input_tokens: {call_kwargs['input_tokens']}")
-        print(f"  output_tokens: {call_kwargs['output_tokens']}")
-        print(f"  response: {response}")
-
-
-@pytest.mark.asyncio
-async def test_llm_metrics_recorded_for_structured_output():
-    """
-    Test that LLM metrics are recorded for structured output (JSON) calls.
-    """
-    api_key = get_groq_api_key()
-    if not api_key:
-        pytest.skip("Skipping: GROQ_API_KEY not set")
-
-    from pydantic import BaseModel
-
-    class SimpleResponse(BaseModel):
-        greeting: str
-        language: str
-
-    mock_collector = MagicMock(spec=MetricsCollector)
-
-    with patch("hindsight_api.engine.llm_wrapper.get_metrics_collector", return_value=mock_collector):
-        llm = LLMProvider(
-            provider="groq",
-            api_key=api_key,
-            base_url="",
-            model="openai/gpt-oss-20b",
-        )
-
-        # Make a structured output call
-        response = await llm.call(
-            messages=[{"role": "user", "content": "Say hello in French. Return greeting and language."}],
-            response_format=SimpleResponse,
-            max_completion_tokens=100,
-            scope="structured_output_test",
-        )
-
-        # Verify structured response
-        assert isinstance(response, SimpleResponse)
-        assert response.greeting is not None
-        assert response.language is not None
-
-        # Verify record_llm_call was called
-        assert mock_collector.record_llm_call.called, "record_llm_call should have been called"
-
-        call_kwargs = mock_collector.record_llm_call.call_args.kwargs
-        assert call_kwargs["input_tokens"] > 0
-        assert call_kwargs["output_tokens"] > 0
-
-        print(f"\nStructured output LLM metrics:")
-        print(f"  greeting: {response.greeting}")
-        print(f"  language: {response.language}")
-        print(f"  input_tokens: {call_kwargs['input_tokens']}")
-        print(f"  output_tokens: {call_kwargs['output_tokens']}")
-
-
-@pytest.mark.asyncio
-async def test_noop_collector_when_metrics_disabled():
-    """
-    Test that NoOpMetricsCollector is returned when metrics are not initialized.
-    This verifies the fallback behavior doesn't break LLM calls.
-    """
-    api_key = get_groq_api_key()
-    if not api_key:
-        pytest.skip("Skipping: GROQ_API_KEY not set")
-
-    # Without initializing metrics, get_metrics_collector returns NoOpMetricsCollector
-    collector = get_metrics_collector()
-    assert isinstance(collector, NoOpMetricsCollector), "Should return NoOpMetricsCollector when not initialized"
-
-    # Make an LLM call - should work fine with NoOp collector
-    llm = LLMProvider(
-        provider="groq",
-        api_key=api_key,
-        base_url="",
-        model="openai/gpt-oss-20b",
-    )
-
-    response = await llm.call(
-        messages=[{"role": "user", "content": "Say 'test' in one word."}],
-        max_completion_tokens=50,
-    )
-
-    assert response is not None
-    print(f"\nLLM call succeeded with NoOpMetricsCollector: {response}")
-
-
-@pytest.mark.asyncio
-async def test_return_usage_returns_tuple():
-    """
-    Test that return_usage=True returns (result, TokenUsage) tuple.
-    """
-    from hindsight_api.engine.response_models import TokenUsage
-
-    api_key = get_groq_api_key()
-    if not api_key:
-        pytest.skip("Skipping: GROQ_API_KEY not set")
-
-    llm = LLMProvider(
-        provider="groq",
-        api_key=api_key,
-        base_url="",
-        model="openai/gpt-oss-20b",
-    )
-
-    # Call with return_usage=True
-    result, usage = await llm.call(
-        messages=[
-            {"role": "system", "content": "You are a helpful assistant."},
-            {"role": "user", "content": "What is 2+2? Reply with just the number."}
-        ],
-        max_completion_tokens=50,
-        return_usage=True,
-    )
-
-    # Verify result is the response text
-    assert result is not None
-    assert isinstance(result, str)
-
-    # Verify usage is TokenUsage model with valid counts
-    assert isinstance(usage, TokenUsage)
-    assert usage.input_tokens > 0, f"Expected input_tokens > 0, got {usage.input_tokens}"
-    assert usage.output_tokens >= 0, f"Expected output_tokens >= 0, got {usage.output_tokens}"
-    assert usage.total_tokens == usage.input_tokens + usage.output_tokens
-
-    print(f"\nreturn_usage=True test:")
-    print(f"  result: {result}")
-    print(f"  usage: {usage}")
-
-
-@pytest.mark.asyncio
-async def test_return_usage_with_structured_output():
-    """
-    Test that return_usage=True works with structured output (JSON).
-    """
-    from pydantic import BaseModel
-    from hindsight_api.engine.response_models import TokenUsage
-
-    api_key = get_groq_api_key()
-    if not api_key:
-        pytest.skip("Skipping: GROQ_API_KEY not set")
-
-    class MathAnswer(BaseModel):
-        answer: int
-        explanation: str
-
-    llm = LLMProvider(
-        provider="groq",
-        api_key=api_key,
-        base_url="",
-        model="openai/gpt-oss-20b",
-    )
-
-    # Call with return_usage=True and structured output
-    result, usage = await llm.call(
-        messages=[{"role": "user", "content": "What is 5+3? Return the answer and a brief explanation."}],
-        response_format=MathAnswer,
-        max_completion_tokens=100,
-        return_usage=True,
-    )
-
-    # Verify result is the parsed response
-    assert isinstance(result, MathAnswer)
-    assert result.answer == 8
-    assert result.explanation is not None
-
-    # Verify usage is TokenUsage model
-    assert isinstance(usage, TokenUsage)
-    assert usage.input_tokens > 0
-    assert usage.output_tokens > 0
-
-    print(f"\nStructured output with return_usage=True:")
-    print(f"  result: {result}")
-    print(f"  usage: {usage}")
@@ -1,325 +0,0 @@
-"""
-Tests for LLM tool calling functionality.
-"""
-
-import pytest
-
-from hindsight_api.engine.llm_wrapper import LLMProvider
-from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult
-
-
-# Sample tools for testing
-SAMPLE_TOOLS = [
-    {
-        "type": "function",
-        "function": {
-            "name": "get_weather",
-            "description": "Get weather for a location",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "location": {"type": "string", "description": "City name"},
-                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
-                },
-                "required": ["location"],
-            },
-        },
-    },
-    {
-        "type": "function",
-        "function": {
-            "name": "search",
-            "description": "Search for information",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query"},
-                },
-                "required": ["query"],
-            },
-        },
-    },
-]
-
-
-class TestMockToolCalling:
-    """Test tool calling with mock provider."""
-
-    @pytest.mark.asyncio
-    async def test_call_with_tools_returns_tool_calls(self):
-        """Test that mock provider can return tool calls."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        # Set mock response to return tool calls
-        llm.set_mock_response([
-            {"name": "get_weather", "arguments": {"location": "Paris", "unit": "celsius"}},
-        ])
-
-        result = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "What's the weather in Paris?"}],
-            tools=SAMPLE_TOOLS,
-        )
-
-        assert isinstance(result, LLMToolCallResult)
-        assert len(result.tool_calls) == 1
-        assert result.tool_calls[0].name == "get_weather"
-        assert result.tool_calls[0].arguments == {"location": "Paris", "unit": "celsius"}
-        assert result.finish_reason == "tool_calls"
-
-    @pytest.mark.asyncio
-    async def test_call_with_tools_returns_content(self):
-        """Test that mock provider can return plain content."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        # Default mock response is plain content
-        result = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "Hello"}],
-            tools=SAMPLE_TOOLS,
-        )
-
-        assert isinstance(result, LLMToolCallResult)
-        assert result.content == "mock response"
-        assert len(result.tool_calls) == 0
-        assert result.finish_reason == "stop"
-
-    @pytest.mark.asyncio
-    async def test_call_with_tools_records_calls(self):
-        """Test that mock calls are recorded."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-        llm.clear_mock_calls()
-
-        await llm.call_with_tools(
-            messages=[{"role": "user", "content": "Test message"}],
-            tools=SAMPLE_TOOLS,
-            scope="test_scope",
-        )
-
-        calls = llm.get_mock_calls()
-        assert len(calls) == 1
-        assert calls[0]["scope"] == "test_scope"
-        assert "get_weather" in calls[0]["tools"]
-        assert "search" in calls[0]["tools"]
-
-    @pytest.mark.asyncio
-    async def test_call_with_tools_multiple_tool_calls(self):
-        """Test handling multiple tool calls in one response."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        llm.set_mock_response([
-            {"name": "get_weather", "arguments": {"location": "Paris"}},
-            {"name": "search", "arguments": {"query": "weather forecast"}},
-        ])
-
-        result = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "Weather in Paris and search for forecasts"}],
-            tools=SAMPLE_TOOLS,
-        )
-
-        assert len(result.tool_calls) == 2
-        assert result.tool_calls[0].name == "get_weather"
-        assert result.tool_calls[1].name == "search"
-
-    @pytest.mark.asyncio
-    async def test_call_with_tools_accepts_llm_tool_call_result(self):
-        """Test that mock can accept LLMToolCallResult directly."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        expected_result = LLMToolCallResult(
-            content="Here's the info",
-            tool_calls=[LLMToolCall(id="call_123", name="search", arguments={"query": "test"})],
-            finish_reason="tool_calls",
-        )
-        llm.set_mock_response(expected_result)
-
-        result = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "Search for test"}],
-            tools=SAMPLE_TOOLS,
-        )
-
-        assert result == expected_result
-
-
-class TestToolCallConversation:
-    """Test tool call conversation flow."""
-
-    @pytest.mark.asyncio
-    async def test_tool_result_message_format(self):
-        """Test that tool result messages can be passed in subsequent calls."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        # First call returns tool call
-        llm.set_mock_response([{"name": "get_weather", "arguments": {"location": "Paris"}}])
-
-        result1 = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "What's the weather?"}],
-            tools=SAMPLE_TOOLS,
-        )
-
-        # Build conversation with tool result
-        messages = [
-            {"role": "user", "content": "What's the weather?"},
-            {
-                "role": "assistant",
-                "tool_calls": [
-                    {
-                        "id": result1.tool_calls[0].id,
-                        "type": "function",
-                        "function": {
-                            "name": result1.tool_calls[0].name,
-                            "arguments": '{"location": "Paris"}',
-                        },
-                    }
-                ],
-            },
-            {
-                "role": "tool",
-                "tool_call_id": result1.tool_calls[0].id,
-                "content": '{"temperature": 20, "conditions": "sunny"}',
-            },
-        ]
-
-        # Second call should work with tool result in history
-        llm.set_mock_response(None)  # Reset to default
-        result2 = await llm.call_with_tools(
-            messages=messages,
-            tools=SAMPLE_TOOLS,
-        )
-
-        assert result2.content == "mock response"
-
-
-class TestToolSchemas:
-    """Test tool schema handling."""
-
-    @pytest.mark.asyncio
-    async def test_empty_tools_list(self):
-        """Test calling with empty tools list."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        result = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "Hello"}],
-            tools=[],
-        )
-
-        assert result.content == "mock response"
-
-    @pytest.mark.asyncio
-    async def test_tool_with_no_required_params(self):
-        """Test tool with no required parameters."""
-        llm = LLMProvider(provider="mock", api_key="", base_url="", model="mock")
-
-        tools = [
-            {
-                "type": "function",
-                "function": {
-                    "name": "list_items",
-                    "description": "List all items",
-                    "parameters": {"type": "object", "properties": {}, "required": []},
-                },
-            }
-        ]
-
-        llm.set_mock_response([{"name": "list_items", "arguments": {}}])
-
-        result = await llm.call_with_tools(
-            messages=[{"role": "user", "content": "List items"}],
-            tools=tools,
-        )
-
-        assert len(result.tool_calls) == 1
-        assert result.tool_calls[0].name == "list_items"
-        assert result.tool_calls[0].arguments == {}
-
-
-class TestReflectToolSchemas:
-    """Test reflect agent tool schemas."""
-
-    def test_get_reflect_tools_default(self):
-        """Test getting default reflect tools."""
-        from hindsight_api.engine.reflect.tools_schema import get_reflect_tools
-
-        tools = get_reflect_tools()
-
-        tool_names = [t["function"]["name"] for t in tools]
-        assert "list_mental_models" in tool_names
-        assert "get_mental_model" in tool_names
-        assert "recall" in tool_names
-        assert "learn" in tool_names
-        assert "expand" in tool_names
-        assert "done" in tool_names
-
-    def test_get_reflect_tools_without_learn(self):
-        """Test getting reflect tools without learn."""
-        from hindsight_api.engine.reflect.tools_schema import get_reflect_tools
-
-        tools = get_reflect_tools(enable_learn=False)
-
-        tool_names = [t["function"]["name"] for t in tools]
-        assert "learn" not in tool_names
-        assert "recall" in tool_names
-        assert "done" in tool_names
-
-    def test_get_reflect_tools_answer_mode(self):
-        """Test getting reflect tools with answer output mode."""
-        from hindsight_api.engine.reflect.tools_schema import get_reflect_tools
-
-        tools = get_reflect_tools()
-
-        done_tool = next(t for t in tools if t["function"]["name"] == "done")
-        params = done_tool["function"]["parameters"]["properties"]
-
-        assert "answer" in params
-        assert "memory_ids" in params
-        assert "model_ids" in params
-
-
-class TestLLMToolCallResult:
-    """Test LLMToolCallResult model."""
-
-    def test_tool_call_result_defaults(self):
-        """Test default values for LLMToolCallResult."""
-        result = LLMToolCallResult()
-
-        assert result.content is None
-        assert result.tool_calls == []
-        assert result.finish_reason is None
-
-    def test_tool_call_result_with_content(self):
-        """Test LLMToolCallResult with content."""
-        result = LLMToolCallResult(content="Hello", finish_reason="stop")
-
-        assert result.content == "Hello"
-        assert result.tool_calls == []
-        assert result.finish_reason == "stop"
-
-    def test_tool_call_result_with_tool_calls(self):
-        """Test LLMToolCallResult with tool calls."""
-        result = LLMToolCallResult(
-            tool_calls=[
-                LLMToolCall(id="call_1", name="test_tool", arguments={"arg": "value"}),
-            ],
-            finish_reason="tool_calls",
-        )
-
-        assert result.content is None
-        assert len(result.tool_calls) == 1
-        assert result.tool_calls[0].name == "test_tool"
-        assert result.finish_reason == "tool_calls"
-
-
-class TestLLMToolCall:
-    """Test LLMToolCall model."""
-
-    def test_tool_call_basic(self):
-        """Test basic LLMToolCall creation."""
-        call = LLMToolCall(id="call_123", name="get_weather", arguments={"location": "Paris"})
-
-        assert call.id == "call_123"
-        assert call.name == "get_weather"
-        assert call.arguments == {"location": "Paris"}
-
-    def test_tool_call_empty_arguments(self):
-        """Test LLMToolCall with empty arguments."""
-        call = LLMToolCall(id="call_456", name="list_items", arguments={})
-
-        assert call.arguments == {}
@@ -1,318 +0,0 @@
-"""
-Load test for large batch retain operations.
-
-Tests batch processing with 20 content items totaling ~500k chars
-using a mock LLM to verify DB and batch size handling.
-"""
-
-import asyncio
-import json
-import logging
-import time
-import uuid
-from datetime import datetime, UTC
-from unittest.mock import AsyncMock, patch, MagicMock
-
-import pytest
-import pytest_asyncio
-
-from hindsight_api import MemoryEngine, LLMConfig, LocalSTEmbeddings, RequestContext
-from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder
-from hindsight_api.engine.query_analyzer import DateparserQueryAnalyzer
-from hindsight_api.engine.task_backend import SyncTaskBackend
-from hindsight_api.engine.retain.fact_extraction import FactExtractionResponse, ExtractedFact
-from hindsight_api.engine.llm_wrapper import TokenUsage
-
-logger = logging.getLogger(__name__)
-
-
-def generate_content(char_count: int) -> str:
-    """Generate realistic content of approximately char_count characters."""
-    # Base sentences that look like real conversations/notes
-    sentences = [
-        "I had a meeting with John about the quarterly projections for Q3.",
-        "We discussed the new marketing strategy and agreed to increase social media presence.",
-        "Sarah mentioned that she's planning to visit Tokyo next month for the conference.",
-        "The project deadline was extended to December 15th after consulting with stakeholders.",
-        "I need to follow up with the engineering team about the API integration issues.",
-        "The budget review showed we're 15% under projections, which is good news.",
-        "Mike suggested we look into alternative vendors for the cloud infrastructure.",
-        "The client feedback from the beta testing was overwhelmingly positive.",
-        "We should schedule another sync meeting for next Tuesday afternoon.",
-        "The documentation needs to be updated before the product launch.",
-        "I learned that Python 3.12 has some great new performance improvements.",
-        "The restaurant downtown has amazing pasta - must remember to go back.",
-        "Emily's birthday is coming up, need to plan something special.",
-        "The new office location will be in the financial district starting January.",
-        "Weather forecast shows rain all week, should bring an umbrella.",
-    ]
-
-    content = []
-    current_chars = 0
-    idx = 0
-
-    while current_chars < char_count:
-        sentence = sentences[idx % len(sentences)]
-        # Add some variation with numbers/dates
-        if idx % 3 == 0:
-            sentence = f"[{datetime.now().strftime('%Y-%m-%d')}] " + sentence
-        content.append(sentence)
-        current_chars += len(sentence) + 1  # +1 for newline
-        idx += 1
-
-    return "\n".join(content)
-
-
-def create_mock_facts_from_content(content: str, ratio: float = 1.5, max_facts: int = 50) -> list[dict]:
-    """
-    Create mock extracted facts from content at the given ratio.
-
-    If content has N sentences, return approximately N * ratio facts (capped at max_facts).
-    """
-    # Estimate sentences by splitting on periods
-    sentences = [s.strip() for s in content.split('.') if s.strip()]
-    num_facts = min(max(1, int(len(sentences) * ratio)), max_facts)
-
-    facts = []
-    for i in range(num_facts):
-        facts.append({
-            "what": f"Mock fact {i}: Something happened based on the content",
-            "when": "2024-06-15",
-            "where": "San Francisco",
-            "who": "John, Sarah",
-            "why": "Business reasons",
-            "fact_type": "world",
-            "entities": [{"text": "John", "type": "PERSON"}],
-            "causal_relations": [],
-        })
-
-    return facts
-
-
-class TestLargeBatchRetain:
-    """Load tests for large batch retain operations."""
-
-    @pytest_asyncio.fixture
-    async def memory_with_mock_llm(self, pg0_db_url, embeddings, cross_encoder, query_analyzer):
-        """Create a memory engine with mocked LLM for testing."""
-        mem = MemoryEngine(
-            db_url=pg0_db_url,
-            memory_llm_provider="openai",  # Will be mocked
-            memory_llm_api_key="mock-key",
-            memory_llm_model="gpt-4",
-            embeddings=embeddings,
-            cross_encoder=cross_encoder,
-            query_analyzer=query_analyzer,
-            pool_min_size=2,
-            pool_max_size=10,
-            run_migrations=False,
-            skip_llm_verification=True,  # Skip LLM verification since we're mocking
-            task_backend=SyncTaskBackend(),  # Execute tasks immediately in tests
-        )
-        await mem.initialize()
-        yield mem
-        try:
-            if mem._pool and not mem._pool._closing:
-                await mem.close()
-        except Exception:
-            pass
-
-    @pytest.mark.asyncio
-    @pytest.mark.timeout(300)  # 5 minute timeout
-    async def test_large_batch_500k_chars_20_items(self, memory_with_mock_llm, request_context):
-        """
-        Test retaining a batch of 20 content items totaling ~500k chars.
-
-        Uses mock LLM with 1.5x output ratio to test DB and batch handling.
-        """
-        memory = memory_with_mock_llm
-        bank_id = f"load-test-{uuid.uuid4().hex[:8]}"
-
-        # Create 20 content items totaling ~50k chars
-        num_items = 20
-        total_target_chars = 50_000
-        chars_per_item = total_target_chars // num_items
-
-        contents = []
-        for i in range(num_items):
-            content_text = generate_content(chars_per_item)
-            contents.append({
-                "content": content_text,
-                "context": f"Test content item {i + 1} of {num_items}",
-                "event_date": datetime.now(UTC),
-            })
-
-        actual_total_chars = sum(len(c["content"]) for c in contents)
-        logger.info(f"Created {num_items} content items with {actual_total_chars:,} total chars")
-
-        # Track LLM calls to verify mock is working
-        call_tracker = {"count": 0, "facts": 0}
-
-        async def mock_llm_call(*args, **kwargs):
-            call_tracker["count"] += 1
-
-            # Extract the content from the user message to generate proportional facts
-            messages = kwargs.get("messages", args[0] if args else [])
-            user_msg = messages[-1]["content"] if messages else ""
-            mock_facts = create_mock_facts_from_content(user_msg, ratio=1.5)
-            call_tracker["facts"] += len(mock_facts)
-
-            # Return a dict (parsed JSON) since skip_validation=True but the code expects a dict
-            response_dict = {"facts": mock_facts}
-
-            return_usage = kwargs.get("return_usage", False)
-            if return_usage:
-                usage = TokenUsage(
-                    input_tokens=len(user_msg) // 4,
-                    output_tokens=len(json.dumps(response_dict)) // 4,
-                )
-                return response_dict, usage
-            return response_dict
-
-        # Patch LLMProvider.call at the class level
-        with patch('hindsight_api.engine.llm_wrapper.LLMProvider.call', new=mock_llm_call):
-            start_time = time.time()
-
-            try:
-                result = await memory.retain_batch_async(
-                    bank_id=bank_id,
-                    contents=contents,
-                    request_context=request_context,
-                )
-
-                elapsed = time.time() - start_time
-
-                # Log results
-                total_units = sum(len(unit_ids) for unit_ids in result)
-                logger.info(f"\n{'=' * 60}")
-                logger.info(f"LOAD TEST RESULTS")
-                logger.info(f"{'=' * 60}")
-                logger.info(f"Input: {num_items} items, {actual_total_chars:,} chars")
-                logger.info(f"LLM calls: {call_tracker['count']}")
-                logger.info(f"Mock facts generated: {call_tracker['facts']}")
-                logger.info(f"Memory units created: {total_units}")
-                logger.info(f"Elapsed time: {elapsed:.2f}s")
-                logger.info(f"Throughput: {actual_total_chars / elapsed:,.0f} chars/sec")
-                logger.info(f"{'=' * 60}")
-
-                # Assertions
-                assert len(result) == num_items, f"Expected {num_items} result lists, got {len(result)}"
-                assert total_units > 0, "Expected at least some memory units to be created"
-                assert call_tracker["count"] > 0, "Expected LLM to be called"
-
-                # Verify we didn't timeout or have major issues
-                assert elapsed < 300, f"Operation took too long: {elapsed:.2f}s"
-
-            except Exception as e:
-                elapsed = time.time() - start_time
-                logger.error(f"LOAD TEST FAILED after {elapsed:.2f}s: {e}")
-                raise
-
-    @pytest.mark.asyncio
-    @pytest.mark.timeout(120)
-    async def test_batch_chunking_behavior(self, memory_with_mock_llm, request_context):
-        """
-        Test that large batches are properly chunked into sub-batches.
-
-        Verifies the CHARS_PER_BATCH (600k) chunking logic.
-        """
-        memory = memory_with_mock_llm
-        bank_id = f"chunk-test-{uuid.uuid4().hex[:8]}"
-
-        # Create contents that are moderately sized
-        # Testing the chunking behavior with smaller content
-        num_items = 5
-        chars_per_item = 10_000  # 50k total
-
-        contents = []
-        for i in range(num_items):
-            contents.append({
-                "content": generate_content(chars_per_item),
-                "context": f"Chunk test item {i + 1}",
-                "event_date": datetime.now(UTC),
-            })
-
-        actual_total_chars = sum(len(c["content"]) for c in contents)
-        logger.info(f"Created {num_items} items with {actual_total_chars:,} chars (should trigger chunking)")
-
-        async def mock_llm_call(*args, **kwargs):
-            messages = kwargs.get("messages", args[0] if args else [])
-            user_msg = messages[-1]["content"] if messages else ""
-            mock_facts = create_mock_facts_from_content(user_msg, ratio=1.0)
-            response_dict = {"facts": mock_facts}
-
-            return_usage = kwargs.get("return_usage", False)
-            if return_usage:
-                return response_dict, TokenUsage(input_tokens=100, output_tokens=50)
-            return response_dict
-
-        with patch('hindsight_api.engine.llm_wrapper.LLMProvider.call', new=mock_llm_call):
-            start_time = time.time()
-
-            result = await memory.retain_batch_async(
-                bank_id=bank_id,
-                contents=contents,
-                request_context=request_context,
-            )
-
-            elapsed = time.time() - start_time
-            total_units = sum(len(unit_ids) for unit_ids in result)
-
-            logger.info(f"Chunking test: {total_units} units in {elapsed:.2f}s")
-
-            assert len(result) == num_items
-            assert total_units > 0
-
-    @pytest.mark.asyncio
-    @pytest.mark.timeout(60)
-    async def test_db_connection_pool_under_load(self, memory_with_mock_llm, request_context):
-        """
-        Test that DB connection pool handles concurrent operations.
-
-        Runs multiple retain operations concurrently to stress the pool.
-        """
-        memory = memory_with_mock_llm
-
-        async def mock_llm_call(*args, **kwargs):
-            # Small delay to simulate real LLM latency
-            await asyncio.sleep(0.01)
-            mock_facts = [{"what": "Test fact", "when": "now", "where": "here",
-                          "who": "someone", "why": "testing", "fact_type": "world",
-                          "entities": [], "causal_relations": []}]
-            response_dict = {"facts": mock_facts}
-
-            return_usage = kwargs.get("return_usage", False)
-            if return_usage:
-                return response_dict, TokenUsage(input_tokens=10, output_tokens=10)
-            return response_dict
-
-        with patch('hindsight_api.engine.llm_wrapper.LLMProvider.call', new=mock_llm_call):
-            # Run 10 concurrent retain operations
-            tasks = []
-            for i in range(10):
-                bank_id = f"pool-test-{uuid.uuid4().hex[:8]}"
-                contents = [{
-                    "content": f"Test content for concurrent operation {i}. " * 50,
-                    "context": f"Pool test {i}",
-                    "event_date": datetime.now(UTC),
-                }]
-                tasks.append(
-                    memory.retain_batch_async(bank_id=bank_id, contents=contents, request_context=request_context)
-                )
-
-            start_time = time.time()
-            results = await asyncio.gather(*tasks, return_exceptions=True)
-            elapsed = time.time() - start_time
-
-            # Check results
-            errors = [r for r in results if isinstance(r, Exception)]
-            successes = [r for r in results if not isinstance(r, Exception)]
-
-            logger.info(f"Pool test: {len(successes)} successes, {len(errors)} errors in {elapsed:.2f}s")
-
-            if errors:
-                for e in errors:
-                    logger.error(f"Error: {e}")
-
-            assert len(errors) == 0, f"Expected no errors, got: {errors}"
-            assert len(successes) == 10
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Nicolò Boschi	bcd5ee3eca	misc: add mcp integration tests and increase test coverage	2026-01-05 11:16:41 +01:00
Nicolò Boschi	16bfb43369	misc: add mcp integration tests and increase test coverage	2026-01-05 11:00:19 +01:00
Nicolò Boschi	099dc7deea	misc: add mcp integration tests and increase test coverage	2026-01-05 10:43:52 +01:00