support tags

feat: add memory tags
2026-01-13 18:18:01 +01:00 · 2026-01-13 18:10:48 +01:00 · 2026-01-13 15:42:54 +01:00 · 2026-01-13 15:30:13 +01:00 · 2026-01-13 13:20:22 +01:00 · 2026-01-12 18:58:05 +01:00
253 changed files with 30969 additions and 15399 deletions
@@ -2,11 +2,23 @@
 # Copy this file to .env and fill in your values

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

+# Example: Anthropic Claude configuration
+# HINDSIGHT_API_LLM_PROVIDER=anthropic
+# HINDSIGHT_API_LLM_API_KEY=your-anthropic-api-key
+# HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-20250514
+
+# Example: LM Studio local configuration (Qwen 2.5 32B recommended)
+# HINDSIGHT_API_LLM_PROVIDER=lmstudio
+# HINDSIGHT_API_LLM_API_KEY=lmstudio
+# HINDSIGHT_API_LLM_BASE_URL=http://localhost:1234/v1
+# HINDSIGHT_API_LLM_MODEL=qwen2.5-32b-instruct
+
 # API Configuration (Optional)
 HINDSIGHT_API_HOST=0.0.0.0
 HINDSIGHT_API_PORT=8888
@@ -0,0 +1,71 @@
+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
+
@@ -0,0 +1,8 @@
+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.
@@ -0,0 +1,82 @@
+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
@@ -222,7 +222,7 @@ jobs:

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

    - name: Create .env file
      run: |
@@ -325,6 +325,8 @@ 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)
@@ -350,7 +352,7 @@ jobs:

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

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

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

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

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

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

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

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

    - name: Create .env file
      run: |
@@ -613,6 +615,97 @@ jobs:
        echo "=== API Server Logs ==="
        cat /tmp/api-server.log || echo "No API server log found"

+  test-integration:
+    runs-on: ubuntu-latest
+    env:
+      HINDSIGHT_API_LLM_PROVIDER: 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: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        prune-cache: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Build API
+      working-directory: ./hindsight-api
+      run: uv build
+
+    - name: Install API dependencies
+      working-directory: ./hindsight-api
+      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+
+    - name: Install integration test dependencies
+      working-directory: ./hindsight-integration-tests
+      run: uv sync --frozen
+
+    - name: Cache HuggingFace models
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/huggingface
+        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-huggingface-
+
+    - name: Pre-download models
+      working-directory: ./hindsight-api
+      run: |
+        uv run python -c "
+        from sentence_transformers import SentenceTransformer, CrossEncoder
+        print('Downloading embedding model...')
+        SentenceTransformer('BAAI/bge-small-en-v1.5')
+        print('Downloading cross-encoder model...')
+        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
+        print('Models downloaded successfully')
+        "
+
+    - name: Create .env file
+      run: |
+        cat > .env << EOF
+        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
+        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
+        EOF
+
+    - name: Start API server
+      run: |
+        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
+        echo "Waiting for API server to be ready..."
+        for i in {1..60}; do
+          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
+            echo "API server is ready after ${i}s"
+            break
+          fi
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
+            cat /tmp/api-server.log
+            exit 1
+          fi
+          sleep 1
+        done
+
+    - name: Run integration tests
+      working-directory: ./hindsight-integration-tests
+      run: uv run pytest tests/ -v
+
+    - name: Show API server logs
+      if: always()
+      run: |
+        echo "=== API Server Logs ==="
+        cat /tmp/api-server.log || echo "No API server log found"
+
  test-litellm-integration:
    runs-on: ubuntu-latest

@@ -636,7 +729,7 @@ jobs:

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

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

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

    - name: Cache HuggingFace models
      uses: actions/cache@v4
@@ -727,11 +820,11 @@ jobs:
      working-directory: ./hindsight-api
      run: |
        uv build
-        uv sync --no-install-project --index-strategy unsafe-best-match
+        uv sync --frozen --no-install-project --index-strategy unsafe-best-match

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

    - name: Install TypeScript client
      run: |
@@ -792,4 +885,76 @@ jobs:
      if: always()
      run: |
        echo "=== API Server Logs ==="
-        cat /tmp/api-server.log || echo "No API server log found"
+        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"
@@ -5,15 +5,18 @@ build/
 dist/
 wheels/
 *.egg-info
-
+.mcp.json
+.osgrep
 # Virtual environments
 .venv

 # Node
 node_modules/

-# Environment variables
+# Environment variables and local config
 .env
+docker-compose.yml
+docker-compose.override.yml

 # IDE
 .idea/
@@ -24,6 +27,10 @@ node_modules/
 # 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

@@ -39,4 +46,8 @@ hindsight-docs/static/llms-full.txt
 hindsight-dev/benchmarks/locomo/results/
 hindsight-dev/benchmarks/longmemeval/results/
 hindsight-cli/target
-hindsight-clients/rust/target
+hindsight-clients/rust/target
+.claude
+whats-next.md
+TASK.md
+CHANGELOG.md
@@ -0,0 +1,251 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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
+
+## Development Commands
+
+### API Server (Python/FastAPI)
+```bash
+# Start API server (loads .env automatically)
+./scripts/dev/start-api.sh
+
+# Run all tests (parallelized with pytest-xdist)
+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
+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)
+```bash
+./scripts/dev/start-control-plane.sh
+# Or manually:
+cd hindsight-control-plane && npm run dev
+```
+
+### Documentation Site (Docusaurus)
+```bash
+./scripts/dev/start-docs.sh
+```
+
+### Generating Clients/OpenAPI
+```bash
+# Regenerate OpenAPI spec after API changes (REQUIRED after changing endpoints)
+./scripts/generate-openapi.sh
+
+# Regenerate all client SDKs (Python, TypeScript, Rust)
+./scripts/generate-clients.sh
+```
+
+### Benchmarks
+```bash
+./scripts/benchmarks/run-longmemeval.sh
+./scripts/benchmarks/run-locomo.sh
+./scripts/benchmarks/start-visualizer.sh  # View results at localhost:8001
+```
+
+## Architecture
+
+### Monorepo Structure
+- **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-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
+- `llm_wrapper.py`: LLM abstraction supporting OpenAI, Anthropic, Gemini, Groq, Ollama, LM Studio
+- `embeddings.py`: Embedding generation (local sentence-transformers 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
+
+### 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:
+- **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)
+
+### 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
+
+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
+
+2. **Migration template**:
+   ```python
+   """Description of the migration
+
+   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
+   ```
+
+## 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)
+- 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
+- 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
+
+### 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
+cp .env.example .env
+# Edit .env with LLM API key
+
+# Python deps
+uv sync --directory hindsight-api/
+
+# Node deps (uses npm workspaces)
+npm install
+```
+
+Required env vars:
+- `HINDSIGHT_API_LLM_PROVIDER`: openai, anthropic, gemini, groq, ollama, lmstudio
+- `HINDSIGHT_API_LLM_API_KEY`: Your API key
+- `HINDSIGHT_API_LLM_MODEL`: Model name (e.g., 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)
@@ -51,7 +51,36 @@ cd hindsight-api
 uv run pytest tests/
 ```

-### Code style
+### Code Style
+
+We use [Ruff](https://docs.astral.sh/ruff/) for Python linting and formatting, and ESLint/Prettier for TypeScript.
+
+#### Setting up git hooks (recommended)
+
+Set up git hooks to automatically lint and format code before each commit:
+
+```bash
+./scripts/setup-hooks.sh
+```
+
+This configures git to use the hooks in `.githooks/`, which run all scripts in `scripts/hooks/` on commit. The lint hook runs in parallel:
+- **Python**: `ruff check --fix`, `ruff format`, `ty check`
+- **TypeScript**: `eslint --fix`, `prettier`
+
+#### Manual linting and formatting
+
+```bash
+# Run all lints (same as pre-commit)
+./scripts/hooks/lint.sh
+
+# Or run individually for Python:
+cd hindsight-api
+uv run ruff check --fix .   # Lint and auto-fix
+uv run ruff format .        # Format code
+uv run ty check hindsight_api  # Type check
+```
+
+#### Style guidelines

 - Use Python type hints
 - Follow existing code patterns
@@ -81,6 +81,8 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
  ghcr.io/vectorize-io/hindsight:latest
 ```

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

@@ -2,19 +2,24 @@
 # 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)
-#   PRELOAD_ML_MODELS=true/false - Pre-download ML models during build (default: true)
+#   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
 #
 # 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
@@ -22,6 +27,7 @@ ARG PRELOAD_ML_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
@@ -40,6 +46,15 @@ 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

@@ -125,7 +140,6 @@ FROM python:3.11-slim AS api-only

 WORKDIR /app

-# Install pg0 dependencies (procps provides 'kill' command needed by pg0)
 # Note: libicu version varies by Debian version - try common versions in order
 RUN apt-get update && apt-get install -y \
    curl \
@@ -138,7 +152,6 @@ RUN apt-get update && apt-get install -y \
    && rm -rf /var/lib/apt/lists/* \
    && pip install --no-cache-dir uv

-# Create non-root user (PostgreSQL cannot run as root)
 RUN useradd -m -s /bin/bash hindsight

 # Copy API with virtual environment from builder
@@ -148,23 +161,17 @@ COPY --from=api-builder /app/api /app/api
 COPY docker/standalone/start-all.sh /app/start-all.sh
 RUN chmod +x /app/start-all.sh

-# Create data directory for pg0 and set ownership
-RUN mkdir -p /app/data && chown -R hindsight:hindsight /app
+RUN chown -R hindsight:hindsight /app

-# Switch to non-root user
 USER hindsight

-# Set PATH for hindsight user
 ENV PATH="/app/api/.venv/bin:${PATH}"

-# Pre-cache PostgreSQL binaries by starting/stopping pg0-embedded
-ENV PG0_HOME=/home/hindsight/.pg0-cache
-
-ENV PG0_HOME=/home/hindsight/.pg0
-
 # 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
-RUN if [ "$PRELOAD_ML_MODELS" = "true" ]; then \
+ARG INCLUDE_LOCAL_MODELS
+RUN if [ "$PRELOAD_ML_MODELS" = "true" ] && [ "$INCLUDE_LOCAL_MODELS" = "true" ]; then \
    /app/api/.venv/bin/python -c "\
 from sentence_transformers import SentenceTransformer, CrossEncoder; \
 print('Downloading embedding model...'); \
@@ -172,6 +179,7 @@ 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
@@ -226,7 +234,7 @@ FROM python:3.11-slim AS standalone

 WORKDIR /app

-# Install Node.js, curl, uv, and pg0 dependencies (procps provides 'kill' command needed by pg0)
+# Install Node.js, curl, uv, and system dependencies
 # Note: libicu version varies by Debian version - try common versions in order
 RUN apt-get update && apt-get install -y \
    curl \
@@ -241,7 +249,6 @@ RUN apt-get update && apt-get install -y \
    && rm -rf /var/lib/apt/lists/* \
    && pip install --no-cache-dir uv

-# Create non-root user (PostgreSQL cannot run as root)
 RUN useradd -m -s /bin/bash hindsight

 # Copy API with virtual environment from builder
@@ -262,30 +269,17 @@ WORKDIR /app
 COPY docker/standalone/start-all.sh /app/start-all.sh
 RUN chmod +x /app/start-all.sh

-# Create data directory for pg0 and set ownership
-RUN mkdir -p /app/data && chown -R hindsight:hindsight /app
+RUN chown -R hindsight:hindsight /app

-# Switch to non-root user
 USER hindsight

-# Set PATH for hindsight user
 ENV PATH="/app/api/.venv/bin:${PATH}"

-# Pre-cache PostgreSQL binaries by starting/stopping pg0-embedded
-ENV PG0_HOME=/home/hindsight/.pg0-cache
-RUN /app/api/.venv/bin/python -c "\
-from pg0 import Pg0; \
-print('Pre-caching PostgreSQL binaries...'); \
-pg = Pg0(name='hindsight', port=5555, username='hindsight', password='hindsight', database='hindsight'); \
-pg.start(); \
-pg.stop(); \
-print('PostgreSQL pre-cached to PG0_HOME')" || echo "Pre-download skipped"
-
-ENV PG0_HOME=/home/hindsight/.pg0
-
 # 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
-RUN if [ "$PRELOAD_ML_MODELS" = "true" ]; then \
+ARG INCLUDE_LOCAL_MODELS
+RUN if [ "$PRELOAD_ML_MODELS" = "true" ] && [ "$INCLUDE_LOCAL_MODELS" = "true" ]; then \
    /app/api/.venv/bin/python -c "\
 from sentence_transformers import SentenceTransformer, CrossEncoder; \
 print('Downloading embedding model...'); \
@@ -293,6 +287,7 @@ 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
@@ -5,16 +5,70 @@ set -e
 ENABLE_API="${HINDSIGHT_ENABLE_API:-true}"
 ENABLE_CP="${HINDSIGHT_ENABLE_CP:-true}"

-# Copy pre-cached PostgreSQL data if runtime directory is empty (first run with volume)
-if [ "$ENABLE_API" = "true" ]; then
-    PG0_CACHE="/home/hindsight/.pg0-cache"
-    PG0_HOME="/home/hindsight/.pg0"
-    if [ -d "$PG0_CACHE" ] && [ "$(ls -A $PG0_CACHE 2>/dev/null)" ]; then
-        if [ ! "$(ls -A $PG0_HOME 2>/dev/null)" ]; then
-            echo "📦 Copying pre-cached PostgreSQL data..."
-            cp -r "$PG0_CACHE"/* "$PG0_HOME"/ 2>/dev/null || true
-        fi
+# =============================================================================
+# Dependency waiting (opt-in via HINDSIGHT_WAIT_FOR_DEPS=true)
+#
+# Problem: When running with LM Studio, the LLM may take time to load models.
+# If Hindsight starts before LM Studio is ready, it fails on LLM verification.
+# This wait loop ensures dependencies are ready before starting.
+# =============================================================================
+if [ "${HINDSIGHT_WAIT_FOR_DEPS:-false}" = "true" ]; then
+    LLM_BASE_URL="${HINDSIGHT_API_LLM_BASE_URL:-http://host.docker.internal:1234/v1}"
+    MAX_RETRIES="${HINDSIGHT_RETRY_MAX:-0}"  # 0 = infinite
+    RETRY_INTERVAL="${HINDSIGHT_RETRY_INTERVAL:-10}"
+
+    # Check if external database is configured (skip check for embedded pg0)
+    SKIP_DB_CHECK=false
+    if [ -z "${HINDSIGHT_API_DATABASE_URL}" ]; then
+        SKIP_DB_CHECK=true
+    else
+        DB_CHECK_HOST=$(echo "$HINDSIGHT_API_DATABASE_URL" | sed -E 's|.*@([^:/]+):([0-9]+)/.*|\1 \2|')
    fi
+
+    check_db() {
+        if $SKIP_DB_CHECK; then
+            return 0
+        fi
+        if command -v pg_isready &> /dev/null; then
+            pg_isready -h $(echo $DB_CHECK_HOST | cut -d' ' -f1) -p $(echo $DB_CHECK_HOST | cut -d' ' -f2) &>/dev/null
+        else
+            python3 -c "import socket; s=socket.socket(); s.settimeout(5); exit(0 if s.connect_ex(('$(echo $DB_CHECK_HOST | cut -d' ' -f1)', $(echo $DB_CHECK_HOST | cut -d' ' -f2))) == 0 else 1)" 2>/dev/null
+        fi
+    }
+
+    check_llm() {
+        curl -sf "${LLM_BASE_URL}/models" --connect-timeout 5 &>/dev/null
+    }
+
+    echo "⏳ Waiting for dependencies to be ready..."
+    attempt=1
+
+    while true; do
+        db_ok=false
+        llm_ok=false
+
+        if check_db; then
+            db_ok=true
+        fi
+
+        if check_llm; then
+            llm_ok=true
+        fi
+
+        if $db_ok && $llm_ok; then
+            echo "✅ Dependencies ready!"
+            break
+        fi
+
+        if [ "$MAX_RETRIES" -ne 0 ] && [ "$attempt" -ge "$MAX_RETRIES" ]; then
+            echo "❌ Max retries ($MAX_RETRIES) reached. Dependencies not available."
+            exit 1
+        fi
+
+        echo "   Attempt $attempt: DB=$( $db_ok && echo 'ok' || echo 'waiting' ), LLM=$( $llm_ok && echo 'ok' || echo 'waiting' )"
+        sleep "$RETRY_INTERVAL"
+        ((attempt++))
+    done
 fi

 # Track PIDs for wait
@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.1.14
-appVersion: "0.1.14"
+version: 0.2.1
+appVersion: "0.2.1"
 keywords:
  - ai
  - memory
@@ -110,3 +110,14 @@ 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,7 +15,9 @@ 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 }}
@@ -37,27 +39,36 @@ spec:
        - name: http
          containerPort: {{ .Values.api.service.targetPort }}
          protocol: TCP
+        {{- if .Values.existingSecret }}
+        envFrom:
+        - secretRef:
+            name: {{ .Values.existingSecret }}
+        {{- end }}
        env:
-        - name: HINDSIGHT_API_DATABASE_URL
-          value: {{ include "hindsight.databaseUrl" . | quote }}
+        {{- /* POSTGRES_PASSWORD must be defined before DATABASE_URL for $(VAR) interpolation */}}
        {{- if not .Values.postgresql.enabled }}
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
-              name: {{ include "hindsight.fullname" . }}-secret
+              name: {{ include "hindsight.secretName" . }}
              key: postgres-password
        {{- end }}
+        - name: HINDSIGHT_API_DATABASE_URL
+          value: {{ include "hindsight.databaseUrl" . | quote }}
        {{- 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.fullname" $ }}-secret
+              name: {{ include "hindsight.secretName" $ }}
              key: {{ $key }}
        {{- end }}
+        {{- end }}
        livenessProbe:
          {{- toYaml .Values.api.livenessProbe | nindent 10 }}
        readinessProbe:
@@ -15,7 +15,9 @@ 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 }}
@@ -37,6 +39,11 @@ 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 }}
@@ -44,13 +51,16 @@ 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.fullname" $ }}-secret
+              name: {{ include "hindsight.secretName" $ }}
              key: {{ $key }}
        {{- end }}
+        {{- end }}
        livenessProbe:
          {{- toYaml .Values.controlPlane.livenessProbe | nindent 10 }}
        readinessProbe:
@@ -1,7 +1,8 @@
+{{- if not .Values.existingSecret }}
 apiVersion: v1
 kind: Secret
 metadata:
-  name: {{ include "hindsight.fullname" . }}-secret
+  name: {{ include "hindsight.secretName" . }}
  labels:
    {{- include "hindsight.labels" . | nindent 4 }}
 type: Opaque
@@ -15,3 +16,4 @@ data:
  {{- if and (not .Values.postgresql.enabled) .Values.postgresql.external.password }}
  postgres-password: {{ .Values.postgresql.external.password | b64enc | quote }}
  {{- end }}
+{{- end }}
@@ -3,6 +3,15 @@
 # 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

@@ -80,7 +80,7 @@ Configure via environment variables:
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `HINDSIGHT_API_DATABASE_URL` | PostgreSQL connection string | `pg0` (embedded) |
-| `HINDSIGHT_API_LLM_PROVIDER` | `openai`, `groq`, `gemini`, `ollama` | `openai` |
+| `HINDSIGHT_API_LLM_PROVIDER` | `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio` | `openai` |
 | `HINDSIGHT_API_LLM_API_KEY` | API key for LLM provider | - |
 | `HINDSIGHT_API_LLM_MODEL` | Model name | `gpt-4o-mini` |
 | `HINDSIGHT_API_HOST` | Server bind address | `0.0.0.0` |
@@ -0,0 +1 @@
+# Admin CLI for Hindsight
@@ -0,0 +1,252 @@
+"""
+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")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,44 @@
+"""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")
@@ -0,0 +1,48 @@
+"""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")
@@ -5,6 +5,7 @@ Provides both HTTP REST API and MCP (Model Context Protocol) server.
 """

 import logging
+from contextlib import asynccontextmanager
 from typing import Optional

 from fastapi import FastAPI
@@ -45,6 +46,18 @@ def create_app(
        # Both HTTP and MCP
        app = create_app(memory, mcp_api_enabled=True)
    """
+    mcp_app = None
+
+    # Create MCP app first if enabled (we need its lifespan for chaining)
+    if mcp_api_enabled:
+        try:
+            from .mcp import create_mcp_app
+
+            mcp_app = create_mcp_app(memory=memory)
+        except ImportError as e:
+            logger.error(f"MCP server requested but dependencies not available: {e}")
+            logger.error("Install with: pip install hindsight-api[mcp]")
+            raise

    # Import and create HTTP API if enabled
    if http_api_enabled:
@@ -57,20 +70,31 @@ def create_app(
        app = FastAPI(title="Hindsight API", version="0.0.7")
        logger.info("HTTP REST API disabled")

-    # Mount MCP server if enabled
-    if mcp_api_enabled:
-        try:
-            from .mcp import create_mcp_app
+    # Mount MCP server and chain its lifespan if enabled
+    if mcp_app is not None:
+        # Get the MCP app's underlying Starlette app for lifespan access
+        mcp_starlette_app = mcp_app.mcp_app

-            # Create MCP app with dynamic bank_id support
-            # Supports: /mcp/{bank_id}/sse (bank-specific SSE endpoint)
-            mcp_app = create_mcp_app(memory=memory)
-            app.mount(mcp_mount_path, mcp_app)
-            logger.info(f"MCP server enabled at {mcp_mount_path}/{{bank_id}}/sse")
-        except ImportError as e:
-            logger.error(f"MCP server requested but dependencies not available: {e}")
-            logger.error("Install with: pip install hindsight-api[mcp]")
-            raise
+        # Store the original lifespan
+        original_lifespan = app.router.lifespan_context
+
+        @asynccontextmanager
+        async def chained_lifespan(app_instance: FastAPI):
+            """Chain the MCP lifespan with the main app lifespan."""
+            # Start MCP lifespan first
+            async with mcp_starlette_app.router.lifespan_context(mcp_starlette_app):
+                logger.info("MCP lifespan started")
+                # Then start the original app lifespan
+                async with original_lifespan(app_instance):
+                    yield
+            logger.info("MCP lifespan stopped")
+
+        # Replace the app's lifespan with the chained version
+        app.router.lifespan_context = chained_lifespan
+
+        # Mount the MCP middleware
+        app.mount(mcp_mount_path, mcp_app)
+        logger.info(f"MCP server enabled at {mcp_mount_path}/")

    return app

@@ -14,6 +14,8 @@ from typing import Any

 from fastapi import Depends, FastAPI, Header, HTTPException, Query

+from hindsight_api.extensions import AuthenticationError
+

 def _parse_metadata(metadata: Any) -> dict[str, Any]:
    """Parse metadata that may be a dict, JSON string, or None."""
@@ -34,8 +36,9 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator
 from hindsight_api import MemoryEngine
 from hindsight_api.engine.db_utils import acquire_with_retry
 from hindsight_api.engine.memory_engine import Budget, fq_table
-from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
-from hindsight_api.extensions import HttpExtension, load_extension
+from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES, TokenUsage
+from hindsight_api.engine.search.tags import TagsMatch
+from hindsight_api.extensions import HttpExtension, OperationValidationError, load_extension
 from hindsight_api.metrics import create_metrics_collector, get_metrics_collector, initialize_metrics
 from hindsight_api.models import RequestContext

@@ -79,6 +82,8 @@ class RecallRequest(BaseModel):
                "trace": True,
                "query_timestamp": "2023-05-30T23:40:00",
                "include": {"entities": {"max_tokens": 500}},
+                "tags": ["user_a"],
+                "tags_match": "any",
            }
        }
    )
@@ -97,6 +102,15 @@ class RecallRequest(BaseModel):
        default_factory=IncludeOptions,
        description="Options for including additional data (entities are included by default)",
    )
+    tags: list[str] | None = Field(
+        default=None,
+        description="Filter memories by tags. If not specified, all memories are returned.",
+    )
+    tags_match: TagsMatch = Field(
+        default="any",
+        description="How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), "
+        "'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).",
+    )


 class RecallResult(BaseModel):
@@ -117,6 +131,7 @@ class RecallResult(BaseModel):
                "document_id": "session_abc123",
                "metadata": {"source": "slack"},
                "chunk_id": "456e7890-e12b-34d5-a678-901234567890",
+                "tags": ["user_a", "user_b"],
            }
        },
    }
@@ -132,6 +147,7 @@ class RecallResult(BaseModel):
    document_id: str | None = None  # Document this memory belongs to
    metadata: dict[str, str] | None = None  # User-defined metadata
    chunk_id: str | None = None  # Chunk this fact was extracted from
+    tags: list[str] | None = None  # Visibility scope tags


 class EntityObservationResponse(BaseModel):
@@ -186,12 +202,18 @@ class EntityListResponse(BaseModel):
                        "first_seen": "2024-01-15T10:30:00Z",
                        "last_seen": "2024-02-01T14:00:00Z",
                    }
-                ]
+                ],
+                "total": 150,
+                "limit": 100,
+                "offset": 0,
            }
        }
    )

    items: list[EntityListItem]
+    total: int
+    limit: int
+    offset: int


 class EntityDetailResponse(BaseModel):
@@ -279,6 +301,13 @@ class RecallResponse(BaseModel):
    chunks: dict[str, ChunkData] | None = Field(default=None, description="Chunks for facts, keyed by chunk_id")


+class EntityInput(BaseModel):
+    """Entity to associate with retained content."""
+
+    text: str = Field(description="The entity name/text")
+    type: str | None = Field(default=None, description="Optional entity type (e.g., 'PERSON', 'ORG', 'CONCEPT')")
+
+
 class MemoryItem(BaseModel):
    """Single memory item for retain."""

@@ -290,6 +319,8 @@ class MemoryItem(BaseModel):
                "context": "team meeting",
                "metadata": {"source": "slack", "channel": "engineering"},
                "document_id": "meeting_notes_2024_01_15",
+                "entities": [{"text": "Alice"}, {"text": "ML model", "type": "CONCEPT"}],
+                "tags": ["user_a", "user_b"],
            }
        },
    )
@@ -299,6 +330,14 @@ class MemoryItem(BaseModel):
    context: str | None = None
    metadata: dict[str, str] | None = None
    document_id: str | None = Field(default=None, description="Optional document ID for this memory item.")
+    entities: list[EntityInput] | None = Field(
+        default=None,
+        description="Optional entities to combine with auto-extracted entities.",
+    )
+    tags: list[str] | None = Field(
+        default=None,
+        description="Optional tags for visibility scoping. Memories with tags can be filtered during recall.",
+    )

    @field_validator("timestamp", mode="before")
    @classmethod
@@ -333,6 +372,7 @@ class RetainRequest(BaseModel):
                    },
                ],
                "async": False,
+                "document_tags": ["user_a", "user_b"],
            }
        }
    )
@@ -343,6 +383,10 @@ class RetainRequest(BaseModel):
        alias="async",
        description="If true, process asynchronously in background. If false, wait for completion (default: false)",
    )
+    document_tags: list[str] | None = Field(
+        default=None,
+        description="Tags applied to all items in this request. These are merged with any item-level tags.",
+    )


 class RetainResponse(BaseModel):
@@ -350,7 +394,15 @@ class RetainResponse(BaseModel):

    model_config = ConfigDict(
        populate_by_name=True,
-        json_schema_extra={"example": {"success": True, "bank_id": "user123", "items_count": 2, "async": False}},
+        json_schema_extra={
+            "example": {
+                "success": True,
+                "bank_id": "user123",
+                "items_count": 2,
+                "async": False,
+                "usage": {"input_tokens": 500, "output_tokens": 100, "total_tokens": 600},
+            }
+        },
    )

    success: bool
@@ -359,6 +411,14 @@ class RetainResponse(BaseModel):
    is_async: bool = Field(
        alias="async", serialization_alias="async", description="Whether the operation was processed asynchronously"
    )
+    operation_id: str | None = Field(
+        default=None,
+        description="Operation ID for tracking async operations. Use GET /v1/default/banks/{bank_id}/operations to list operations and find this ID. Only present when async=true.",
+    )
+    usage: TokenUsage | None = Field(
+        default=None,
+        description="Token usage metrics for LLM calls during fact extraction (only present for synchronous operations)",
+    )


 class FactsIncludeOptions(BaseModel):
@@ -385,7 +445,18 @@ class ReflectRequest(BaseModel):
                "query": "What do you think about artificial intelligence?",
                "budget": "low",
                "context": "This is for a research paper on AI ethics",
+                "max_tokens": 4096,
                "include": {"facts": {}},
+                "response_schema": {
+                    "type": "object",
+                    "properties": {
+                        "summary": {"type": "string"},
+                        "key_points": {"type": "array", "items": {"type": "string"}},
+                    },
+                    "required": ["summary", "key_points"],
+                },
+                "tags": ["user_a"],
+                "tags_match": "any",
            }
        }
    )
@@ -393,9 +464,23 @@ class ReflectRequest(BaseModel):
    query: str
    budget: Budget = Budget.LOW
    context: str | None = None
+    max_tokens: int = Field(default=4096, description="Maximum tokens for the response")
    include: ReflectIncludeOptions = Field(
        default_factory=ReflectIncludeOptions, description="Options for including additional data (disabled by default)"
    )
+    response_schema: dict | None = Field(
+        default=None,
+        description="Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema.",
+    )
+    tags: list[str] | None = Field(
+        default=None,
+        description="Filter memories by tags during reflection. If not specified, all memories are considered.",
+    )
+    tags_match: TagsMatch = Field(
+        default="any",
+        description="How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), "
+        "'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).",
+    )


 class OpinionItem(BaseModel):
@@ -440,12 +525,25 @@ class ReflectResponse(BaseModel):
                    {"id": "123", "text": "AI is used in healthcare", "type": "world"},
                    {"id": "456", "text": "I discussed AI applications last week", "type": "experience"},
                ],
+                "structured_output": {
+                    "summary": "AI is transformative",
+                    "key_points": ["Used in healthcare", "Discussed recently"],
+                },
+                "usage": {"input_tokens": 1500, "output_tokens": 500, "total_tokens": 2000},
            }
        }
    )

    text: str
    based_on: list[ReflectFact] = []  # Facts used to generate the response
+    structured_output: dict | None = Field(
+        default=None,
+        description="Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request.",
+    )
+    usage: TokenUsage | None = Field(
+        default=None,
+        description="Token usage metrics for LLM calls during reflection.",
+    )


 class BanksResponse(BaseModel):
@@ -594,6 +692,7 @@ class GraphDataResponse(BaseModel):
                    }
                ],
                "total_units": 2,
+                "limit": 1000,
            }
        }
    )
@@ -602,6 +701,7 @@ class GraphDataResponse(BaseModel):
    edges: list[dict[str, Any]]
    table_rows: list[dict[str, Any]]
    total_units: int
+    limit: int


 class ListMemoryUnitsResponse(BaseModel):
@@ -663,6 +763,37 @@ class ListDocumentsResponse(BaseModel):
    offset: int


+class TagItem(BaseModel):
+    """Single tag with usage count."""
+
+    tag: str = Field(description="The tag value")
+    count: int = Field(description="Number of memories with this tag")
+
+
+class ListTagsResponse(BaseModel):
+    """Response model for list tags endpoint."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "items": [
+                    {"tag": "user:alice", "count": 42},
+                    {"tag": "user:bob", "count": 15},
+                    {"tag": "session:abc123", "count": 8},
+                ],
+                "total": 25,
+                "limit": 100,
+                "offset": 0,
+            }
+        }
+    )
+
+    items: list[TagItem]
+    total: int
+    limit: int
+    offset: int
+
+
 class DocumentResponse(BaseModel):
    """Response model for get document endpoint."""

@@ -676,6 +807,7 @@ class DocumentResponse(BaseModel):
                "created_at": "2024-01-15T10:30:00Z",
                "updated_at": "2024-01-15T10:30:00Z",
                "memory_unit_count": 15,
+                "tags": ["user_a", "session_123"],
            }
        }
    )
@@ -687,6 +819,7 @@ class DocumentResponse(BaseModel):
    created_at: str
    updated_at: str
    memory_unit_count: int
+    tags: list[str] = Field(default_factory=list, description="Tags associated with this document")


 class DeleteDocumentResponse(BaseModel):
@@ -898,6 +1031,12 @@ def create_app(
            await memory.initialize()
            logging.info("Memory system initialized")

+            # Set up DB pool metrics after memory initialization
+            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)
+                logging.info("DB pool metrics configured")
+
        # Call HTTP extension startup hook
        if http_extension:
            await http_extension.on_startup()
@@ -934,6 +1073,30 @@ def create_app(
    # This is required for mounted sub-applications where lifespan may not fire
    app.state.memory = memory

+    # Add HTTP metrics middleware
+    @app.middleware("http")
+    async def http_metrics_middleware(request, call_next):
+        """Record HTTP request metrics."""
+        # Normalize endpoint path to reduce cardinality
+        # Replace UUIDs and numeric IDs with placeholders
+        import re
+
+        from starlette.requests import Request
+
+        path = request.url.path
+        # Replace UUIDs
+        path = re.sub(r"/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", "/{id}", path)
+        # Replace numeric IDs
+        path = re.sub(r"/\d+(?=/|$)", "/{id}", path)
+
+        status_code = [500]  # Default to 500, will be updated
+        metrics_collector = get_metrics_collector()
+
+        with metrics_collector.record_http_request(request.method, path, lambda: status_code[0]):
+            response = await call_next(request)
+            status_code[0] = response.status_code
+            return response
+
    # Register all routes
    _register_routes(app)

@@ -967,6 +1130,16 @@ def _register_routes(app: FastAPI):
                api_key = authorization.strip()
        return RequestContext(api_key=api_key)

+    # Global exception handler for authentication errors
+    @app.exception_handler(AuthenticationError)
+    async def authentication_error_handler(request, exc: AuthenticationError):
+        from fastapi.responses import JSONResponse
+
+        return JSONResponse(
+            status_code=401,
+            content={"detail": str(exc)},
+        )
+
    @app.get(
        "/health",
        summary="Health check endpoint",
@@ -1003,17 +1176,22 @@ def _register_routes(app: FastAPI):
        "/v1/default/banks/{bank_id}/graph",
        response_model=GraphDataResponse,
        summary="Get memory graph data",
-        description="Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.",
+        description="Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion).",
        operation_id="get_graph",
        tags=["Memory"],
    )
    async def api_graph(
-        bank_id: str, type: str | None = None, request_context: RequestContext = Depends(get_request_context)
+        bank_id: str,
+        type: str | None = None,
+        limit: int = 1000,
+        request_context: RequestContext = Depends(get_request_context),
    ):
        """Get graph data from database, filtered by bank_id and optionally by type."""
        try:
-            data = await app.state.memory.get_graph_data(bank_id, type, request_context=request_context)
+            data = await app.state.memory.get_graph_data(bank_id, type, limit=limit, request_context=request_context)
            return data
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1060,6 +1238,8 @@ def _register_routes(app: FastAPI):
                request_context=request_context,
            )
            return data
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1067,6 +1247,37 @@ def _register_routes(app: FastAPI):
            logger.error(f"Error in /v1/default/banks/{bank_id}/memories/list: {error_detail}")
            raise HTTPException(status_code=500, detail=str(e))

+    @app.get(
+        "/v1/default/banks/{bank_id}/memories/{memory_id}",
+        summary="Get memory unit",
+        description="Get a single memory unit by ID with all its metadata including entities and tags.",
+        operation_id="get_memory",
+        tags=["Memory"],
+    )
+    async def api_get_memory(
+        bank_id: str,
+        memory_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """Get a single memory unit by ID."""
+        try:
+            data = await app.state.memory.get_memory_unit(
+                bank_id=bank_id,
+                memory_id=memory_id,
+                request_context=request_context,
+            )
+            if data is None:
+                raise HTTPException(status_code=404, detail=f"Memory unit '{memory_id}' not found")
+            return data
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in /v1/default/banks/{bank_id}/memories/{memory_id}: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
    @app.post(
        "/v1/default/banks/{bank_id}/memories/recall",
        response_model=RecallResponse,
@@ -1084,6 +1295,9 @@ def _register_routes(app: FastAPI):
        bank_id: str, request: RecallRequest, request_context: RequestContext = Depends(get_request_context)
    ):
        """Run a recall and return results with trace."""
+        import time
+
+        handler_start = time.time()
        metrics = get_metrics_collector()

        try:
@@ -1109,10 +1323,12 @@ def _register_routes(app: FastAPI):
            include_chunks = request.include.chunks is not None
            max_chunk_tokens = request.include.chunks.max_tokens if include_chunks else 8192

+            pre_recall = time.time() - handler_start
            # Run recall with tracing (record metrics)
            with metrics.record_operation(
-                "recall", bank_id=bank_id, budget=request.budget.value, max_tokens=request.max_tokens
+                "recall", bank_id=bank_id, source="api", budget=request.budget.value, max_tokens=request.max_tokens
            ):
+                recall_start = time.time()
                core_result = await app.state.memory.recall_async(
                    bank_id=bank_id,
                    query=request.query,
@@ -1126,6 +1342,8 @@ def _register_routes(app: FastAPI):
                    include_chunks=include_chunks,
                    max_chunk_tokens=max_chunk_tokens,
                    request_context=request_context,
+                    tags=request.tags,
+                    tags_match=request.tags_match,
                )

            # Convert core MemoryFact objects to API RecallResult objects (excluding internal metrics)
@@ -1141,6 +1359,7 @@ def _register_routes(app: FastAPI):
                    mentioned_at=fact.mentioned_at,
                    document_id=fact.document_id,
                    chunk_id=fact.chunk_id,
+                    tags=fact.tags,
                )
                for fact in core_result.results
            ]
@@ -1171,16 +1390,35 @@ def _register_routes(app: FastAPI):
                        ],
                    )

-            return RecallResponse(
+            response = RecallResponse(
                results=recall_results, trace=core_result.trace, entities=entities_response, chunks=chunks_response
            )
+
+            handler_duration = time.time() - handler_start
+            recall_duration = time.time() - recall_start
+            post_recall = handler_duration - pre_recall - recall_duration
+            if handler_duration > 1.0:
+                logging.info(
+                    f"[RECALL HTTP] bank={bank_id} handler_total={handler_duration:.3f}s "
+                    f"pre={pre_recall:.3f}s recall={recall_duration:.3f}s post={post_recall:.3f}s "
+                    f"results={len(recall_results)} entities={len(entities_response) if entities_response else 0}"
+                )
+
+            return response
        except HTTPException:
            raise
+        except OperationValidationError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.reason)
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

+            handler_duration = time.time() - handler_start
            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in /v1/default/banks/{bank_id}/memories/recall: {error_detail}")
+            logger.error(
+                f"[RECALL ERROR] bank={bank_id} handler_duration={handler_duration:.3f}s error={str(e)}\n{error_detail}"
+            )
            raise HTTPException(status_code=500, detail=str(e))

    @app.post(
@@ -1205,13 +1443,17 @@ def _register_routes(app: FastAPI):

        try:
            # Use the memory system's reflect_async method (record metrics)
-            with metrics.record_operation("reflect", bank_id=bank_id, budget=request.budget.value):
+            with metrics.record_operation("reflect", bank_id=bank_id, source="api", budget=request.budget.value):
                core_result = await app.state.memory.reflect_async(
                    bank_id=bank_id,
                    query=request.query,
                    budget=request.budget,
                    context=request.context,
+                    max_tokens=request.max_tokens,
+                    response_schema=request.response_schema,
                    request_context=request_context,
+                    tags=request.tags,
+                    tags_match=request.tags_match,
                )

            # Convert core MemoryFact objects to API ReflectFact objects if facts are requested
@@ -1233,8 +1475,14 @@ def _register_routes(app: FastAPI):
            return ReflectResponse(
                text=core_result.text,
                based_on=based_on_facts,
+                structured_output=core_result.structured_output,
+                usage=core_result.usage,
            )

+        except OperationValidationError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.reason)
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1255,6 +1503,8 @@ def _register_routes(app: FastAPI):
        try:
            banks = await app.state.memory.list_banks(request_context=request_context)
            return BankListResponse(banks=banks)
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1270,9 +1520,14 @@ def _register_routes(app: FastAPI):
        operation_id="get_agent_stats",
        tags=["Banks"],
    )
-    async def api_stats(bank_id: str):
+    async def api_stats(
+        bank_id: str,
+        request_context: RequestContext = Depends(get_request_context),
+    ):
        """Get statistics about memory nodes and links for a memory bank."""
        try:
+            # Authenticate and set tenant schema
+            await app.state.memory._authenticate_tenant(request_context)
            pool = await app.state.memory._get_pool()
            async with acquire_with_retry(pool) as conn:
                # Get node counts by fact_type
@@ -1378,6 +1633,8 @@ def _register_routes(app: FastAPI):
                    failed_operations=failed_operations,
                )

+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1389,19 +1646,29 @@ def _register_routes(app: FastAPI):
        "/v1/default/banks/{bank_id}/entities",
        response_model=EntityListResponse,
        summary="List entities",
-        description="List all entities (people, organizations, etc.) known by the bank, ordered by mention count.",
+        description="List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.",
        operation_id="list_entities",
        tags=["Entities"],
    )
    async def api_list_entities(
        bank_id: str,
        limit: int = Query(default=100, description="Maximum number of entities to return"),
+        offset: int = Query(default=0, description="Offset for pagination"),
        request_context: RequestContext = Depends(get_request_context),
    ):
-        """List entities for a memory bank."""
+        """List entities for a memory bank with pagination."""
        try:
-            entities = await app.state.memory.list_entities(bank_id, limit=limit, request_context=request_context)
-            return EntityListResponse(items=[EntityListItem(**e) for e in entities])
+            data = await app.state.memory.list_entities(
+                bank_id, limit=limit, offset=offset, request_context=request_context
+            )
+            return EntityListResponse(
+                items=[EntityListItem(**e) for e in data["items"]],
+                total=data["total"],
+                limit=data["limit"],
+                offset=data["offset"],
+            )
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1439,7 +1706,7 @@ def _register_routes(app: FastAPI):
                    for obs in entity["observations"]
                ],
            )
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
            raise
        except Exception as e:
            import traceback
@@ -1492,7 +1759,7 @@ def _register_routes(app: FastAPI):
                    for obs in entity["observations"]
                ],
            )
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
            raise
        except Exception as e:
            import traceback
@@ -1530,6 +1797,8 @@ def _register_routes(app: FastAPI):
                bank_id=bank_id, search_query=q, limit=limit, offset=offset, request_context=request_context
            )
            return data
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1538,7 +1807,7 @@ def _register_routes(app: FastAPI):
            raise HTTPException(status_code=500, detail=str(e))

    @app.get(
-        "/v1/default/banks/{bank_id}/documents/{document_id}",
+        "/v1/default/banks/{bank_id}/documents/{document_id:path}",
        response_model=DocumentResponse,
        summary="Get document details",
        description="Get a specific document including its original text",
@@ -1560,7 +1829,7 @@ def _register_routes(app: FastAPI):
            if not document:
                raise HTTPException(status_code=404, detail="Document not found")
            return document
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
            raise
        except Exception as e:
            import traceback
@@ -1570,7 +1839,60 @@ def _register_routes(app: FastAPI):
            raise HTTPException(status_code=500, detail=str(e))

    @app.get(
-        "/v1/default/chunks/{chunk_id}",
+        "/v1/default/banks/{bank_id}/tags",
+        response_model=ListTagsResponse,
+        summary="List tags",
+        description="List all unique tags in a memory bank with usage counts. "
+        "Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.",
+        operation_id="list_tags",
+        tags=["Memory"],
+    )
+    async def api_list_tags(
+        bank_id: str,
+        q: str | None = Query(
+            default=None,
+            description="Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). "
+            "Use '*' as wildcard. Case-insensitive.",
+        ),
+        limit: int = Query(default=100, description="Maximum number of tags to return"),
+        offset: int = Query(default=0, description="Offset for pagination"),
+        request_context: RequestContext = Depends(get_request_context),
+    ):
+        """
+        List all unique tags in a memory bank.
+
+        Use this endpoint to discover available tags or expand wildcard patterns.
+        Supports '*' wildcards for flexible matching (case-insensitive):
+        - 'user:*' matches user:alice, user:bob
+        - '*-admin' matches role-admin, super-admin
+        - 'env*-prod' matches env-prod, environment-prod
+
+        Args:
+            bank_id: Memory Bank ID (from path)
+            q: Wildcard pattern to filter tags (use '*' as wildcard)
+            limit: Maximum number of tags to return (default: 100)
+            offset: Offset for pagination (default: 0)
+        """
+        try:
+            data = await app.state.memory.list_tags(
+                bank_id=bank_id,
+                pattern=q,
+                limit=limit,
+                offset=offset,
+                request_context=request_context,
+            )
+            return data
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in /v1/default/banks/{bank_id}/tags: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.get(
+        "/v1/default/chunks/{chunk_id:path}",
        response_model=ChunkResponse,
        summary="Get chunk details",
        description="Get a specific chunk by its ID",
@@ -1589,7 +1911,7 @@ def _register_routes(app: FastAPI):
            if not chunk:
                raise HTTPException(status_code=404, detail="Chunk not found")
            return chunk
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
            raise
        except Exception as e:
            import traceback
@@ -1599,7 +1921,7 @@ def _register_routes(app: FastAPI):
            raise HTTPException(status_code=500, detail=str(e))

    @app.delete(
-        "/v1/default/banks/{bank_id}/documents/{document_id}",
+        "/v1/default/banks/{bank_id}/documents/{document_id:path}",
        response_model=DeleteDocumentResponse,
        summary="Delete a document",
        description="Delete a document and all its associated memory units and links.\n\n"
@@ -1633,7 +1955,7 @@ def _register_routes(app: FastAPI):
                document_id=document_id,
                memory_units_deleted=result["memory_units_deleted"],
            )
-        except HTTPException:
+        except (AuthenticationError, HTTPException):
            raise
        except Exception as e:
            import traceback
@@ -1658,6 +1980,8 @@ def _register_routes(app: FastAPI):
                bank_id=bank_id,
                operations=[OperationResponse(**op) for op in operations],
            )
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1688,6 +2012,8 @@ def _register_routes(app: FastAPI):
            return CancelOperationResponse(**result)
        except ValueError as e:
            raise HTTPException(status_code=404, detail=str(e))
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1719,6 +2045,8 @@ def _register_routes(app: FastAPI):
                disposition=DispositionTraits(**disposition_dict),
                background=profile["background"],
            )
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1757,6 +2085,8 @@ def _register_routes(app: FastAPI):
                disposition=DispositionTraits(**disposition_dict),
                background=profile["background"],
            )
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1786,6 +2116,8 @@ def _register_routes(app: FastAPI):
                response.disposition = DispositionTraits(**result["disposition"])

            return response
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1837,6 +2169,8 @@ def _register_routes(app: FastAPI):
                disposition=DispositionTraits(**disposition_dict),
                background=final_profile["background"],
            )
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1864,6 +2198,8 @@ def _register_routes(app: FastAPI):
                + result.get("entities_deleted", 0)
                + result.get("documents_deleted", 0),
            )
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1915,29 +2251,44 @@ def _register_routes(app: FastAPI):
                    content_dict["metadata"] = item.metadata
                if item.document_id:
                    content_dict["document_id"] = item.document_id
+                if item.entities:
+                    content_dict["entities"] = [{"text": e.text, "type": e.type or "CONCEPT"} for e in item.entities]
+                if item.tags:
+                    content_dict["tags"] = item.tags
                contents.append(content_dict)

            if request.async_:
                # Async processing: queue task and return immediately
-                result = await app.state.memory.submit_async_retain(bank_id, contents, request_context=request_context)
+                result = await app.state.memory.submit_async_retain(
+                    bank_id, contents, document_tags=request.document_tags, request_context=request_context
+                )
                return RetainResponse.model_validate(
                    {
                        "success": True,
                        "bank_id": bank_id,
                        "items_count": result["items_count"],
                        "async": True,
+                        "operation_id": result["operation_id"],
                    }
                )
            else:
                # Synchronous processing: wait for completion (record metrics)
-                with metrics.record_operation("retain", bank_id=bank_id):
-                    result = await app.state.memory.retain_batch_async(
-                        bank_id=bank_id, contents=contents, request_context=request_context
+                with metrics.record_operation("retain", bank_id=bank_id, source="api"):
+                    result, usage = await app.state.memory.retain_batch_async(
+                        bank_id=bank_id,
+                        contents=contents,
+                        document_tags=request.document_tags,
+                        request_context=request_context,
+                        return_usage=True,
                    )

                return RetainResponse.model_validate(
-                    {"success": True, "bank_id": bank_id, "items_count": len(contents), "async": False}
+                    {"success": True, "bank_id": bank_id, "items_count": len(contents), "async": False, "usage": usage}
                )
+        except OperationValidationError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.reason)
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -1976,6 +2327,8 @@ def _register_routes(app: FastAPI):
            await app.state.memory.delete_bank(bank_id, fact_type=type, request_context=request_context)

            return DeleteResponse(success=True)
+        except (AuthenticationError, HTTPException):
+            raise
        except Exception as e:
            import traceback

@@ -27,12 +27,15 @@ logging.basicConfig(
 )
 logger = logging.getLogger(__name__)

-# Context variable to hold the current bank_id from the URL path
+# Default bank_id from environment variable
+DEFAULT_BANK_ID = os.environ.get("HINDSIGHT_MCP_BANK_ID", "default")
+
+# Context variable to hold the current bank_id
 _current_bank_id: ContextVar[str | None] = ContextVar("current_bank_id", default=None)


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


@@ -44,12 +47,18 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
        memory: MemoryEngine instance (required)

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

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

@@ -65,21 +74,34 @@ 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:
-            bank_id = get_current_bank_id()
-            if bank_id is None:
+            target_bank = bank_id or get_current_bank_id()
+            if target_bank is None:
                return "Error: No bank_id configured"
-            await memory.retain_batch_async(
-                bank_id=bank_id, contents=[{"content": content, "context": context}], request_context=RequestContext()
-            )
-            return "Memory stored successfully"
+            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}'"
        except Exception as e:
            logger.error(f"Error storing memory: {e}", exc_info=True)
            return f"Error: {str(e)}"

    @mcp.tool()
-    async def recall(query: str, max_results: int = 10) -> str:
+    async def recall(query: str, max_tokens: int = 4096, bank_id: str | None = None) -> str:
        """
        Search memories to provide personalized, context-aware responses.

@@ -91,49 +113,165 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:

        Args:
            query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
-            max_results: Maximum number of results to return (default: 10)
+            max_tokens: Maximum tokens in the response (default: 4096)
+            bank_id: Optional bank to search in (defaults to session bank). Use for cross-bank operations.
        """
        try:
-            bank_id = get_current_bank_id()
-            if bank_id is None:
+            target_bank = bank_id or get_current_bank_id()
+            if target_bank is None:
                return "Error: No bank_id configured"
            from hindsight_api.engine.memory_engine import Budget

-            search_result = await memory.recall_async(
-                bank_id=bank_id,
+            recall_result = await memory.recall_async(
+                bank_id=target_bank,
                query=query,
                fact_type=list(VALID_RECALL_FACT_TYPES),
-                budget=Budget.LOW,
+                budget=Budget.HIGH,
+                max_tokens=max_tokens,
                request_context=RequestContext(),
            )

-            results = [
-                {
-                    "id": fact.id,
-                    "text": fact.text,
-                    "type": fact.fact_type,
-                    "context": fact.context,
-                    "occurred_start": fact.occurred_start,
-                }
-                for fact in search_result.results[:max_results]
-            ]
-
-            return json.dumps({"results": results}, indent=2)
+            # Use model's JSON serialization
+            return recall_result.model_dump_json(indent=2)
        except Exception as e:
            logger.error(f"Error searching: {e}", exc_info=True)
-            return json.dumps({"error": str(e), "results": []})
+            return f'{{"error": "{e}", "results": []}}'
+
+    @mcp.tool()
+    async def reflect(query: str, context: str | None = None, budget: str = "low", bank_id: str | None = None) -> str:
+        """
+        Generate thoughtful analysis by synthesizing stored memories with the bank's personality.
+
+        WHEN TO USE THIS TOOL:
+        Use reflect when you need reasoned analysis, not just fact retrieval. This tool
+        thinks through the question using everything the bank knows and its personality traits.
+
+        EXAMPLES OF GOOD QUERIES:
+        - "What patterns have emerged in how I approach debugging?"
+        - "Based on my past decisions, what architectural style do I prefer?"
+        - "What might be the best approach for this problem given what you know about me?"
+        - "How should I prioritize these tasks based on my goals?"
+
+        HOW IT DIFFERS FROM RECALL:
+        - recall: Returns raw facts matching your search (fast lookup)
+        - reflect: Reasons across memories to form a synthesized answer (deeper analysis)
+
+        Use recall for "what did I say about X?" and reflect for "what should I do about X?"
+
+        Args:
+            query: The question or topic to reflect on
+            context: Optional context about why this reflection is needed
+            budget: Search budget - 'low', 'mid', or 'high' (default: 'low')
+            bank_id: Optional bank to reflect 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"
+            from hindsight_api.engine.memory_engine import Budget
+
+            # Map string budget to enum
+            budget_map = {"low": Budget.LOW, "mid": Budget.MID, "high": Budget.HIGH}
+            budget_enum = budget_map.get(budget.lower(), Budget.LOW)
+
+            reflect_result = await memory.reflect_async(
+                bank_id=target_bank,
+                query=query,
+                budget=budget_enum,
+                context=context,
+                request_context=RequestContext(),
+            )
+
+            return reflect_result.model_dump_json(indent=2)
+        except Exception as e:
+            logger.error(f"Error reflecting: {e}", exc_info=True)
+            return f'{{"error": "{e}", "text": ""}}'
+
+    @mcp.tool()
+    async def list_banks() -> str:
+        """
+        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").
+
+        Returns:
+            JSON list of banks with their IDs, names, dispositions, and backgrounds.
+        """
+        try:
+            banks = await memory.list_banks(request_context=RequestContext())
+            return json.dumps({"banks": banks}, indent=2)
+        except Exception as e:
+            logger.error(f"Error listing banks: {e}", exc_info=True)
+            return f'{{"error": "{e}", "banks": []}}'
+
+    @mcp.tool()
+    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.
+
+        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.
+
+        Args:
+            bank_id: Unique identifier for the bank (e.g., 'user-123', 'agent-alpha')
+            name: Optional human-friendly name for the bank
+            background: Optional background context about the bank's owner/purpose
+        """
+        try:
+            # get_bank_profile auto-creates bank if it doesn't exist
+            profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())
+
+            # Update name/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(),
+                )
+                # 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)
+        except Exception as e:
+            logger.error(f"Error creating bank: {e}", exc_info=True)
+            return f'{{"error": "{e}"}}'

    return mcp


 class MCPMiddleware:
-    """ASGI middleware that extracts bank_id from path and sets context."""
+    """ASGI middleware that extracts bank_id from header or path and sets context.
+
+    Bank ID can be provided via:
+    1. X-Bank-Id header (recommended for Claude Code)
+    2. URL path: /mcp/{bank_id}/
+    3. Environment variable HINDSIGHT_MCP_BANK_ID (fallback default)
+
+    For Claude Code, configure with:
+        claude mcp add --transport http hindsight http://localhost:8888/mcp \\
+            --header "X-Bank-Id: my-bank"
+    """

    def __init__(self, app, memory: MemoryEngine):
        self.app = app
        self.memory = memory
        self.mcp_server = create_mcp_server(memory)
-        self.mcp_app = self.mcp_server.http_app()
+        self.mcp_app = self.mcp_server.http_app(path="/")
+        # Expose the lifespan for the parent app to chain
+        self.lifespan = self.mcp_app.lifespan_handler if hasattr(self.mcp_app, "lifespan_handler") else None
+
+    def _get_header(self, scope: dict, name: str) -> str | None:
+        """Extract a header value from ASGI scope."""
+        name_lower = name.lower().encode()
+        for header_name, header_value in scope.get("headers", []):
+            if header_name.lower() == name_lower:
+                return header_value.decode()
+        return None

    async def __call__(self, scope, receive, send):
        if scope["type"] != "http":
@@ -150,32 +288,39 @@ class MCPMiddleware:
        # Also handle case where mount path wasn't stripped (e.g., /mcp/...)
        if path.startswith("/mcp/"):
            path = path[4:]  # Remove /mcp prefix
+        elif path == "/mcp":
+            path = "/"

-        # Extract bank_id from path: /{bank_id}/ or /{bank_id}
-        # http_app expects requests at /
-        if not path.startswith("/") or len(path) <= 1:
-            # No bank_id in path - return error
-            await self._send_error(send, 400, "bank_id required in path: /mcp/{bank_id}/")
-            return
+        # Try to get bank_id from header first (for Claude Code compatibility)
+        bank_id = self._get_header(scope, "X-Bank-Id")

-        # Extract bank_id from first path segment
-        parts = path[1:].split("/", 1)
-        if not parts[0]:
-            await self._send_error(send, 400, "bank_id required in path: /mcp/{bank_id}/")
-            return
+        # MCP endpoint paths that should not be treated as bank_ids
+        MCP_ENDPOINTS = {"sse", "messages"}

-        bank_id = parts[0]
-        new_path = "/" + parts[1] if len(parts) > 1 else "/"
+        # If no header, try to extract from path: /{bank_id}/...
+        new_path = path
+        if not bank_id and path.startswith("/") and len(path) > 1:
+            parts = path[1:].split("/", 1)
+            # Don't treat MCP endpoints as bank_ids
+            if parts[0] and parts[0] not in MCP_ENDPOINTS:
+                # First segment looks like a bank_id
+                bank_id = parts[0]
+                new_path = "/" + parts[1] if len(parts) > 1 else "/"
+
+        # Fall back to default bank_id
+        if not bank_id:
+            bank_id = DEFAULT_BANK_ID
+            logger.debug(f"Using default bank_id: {bank_id}")

        # Set bank_id context
        token = _current_bank_id.set(bank_id)
        try:
            new_scope = scope.copy()
            new_scope["path"] = new_path
+            # Clear root_path since we're passing directly to the app
+            new_scope["root_path"] = ""

-            # Wrap send to rewrite the SSE endpoint URL to include bank_id
-            # The SSE app sends "event: endpoint\ndata: /messages\n" but we need
-            # the client to POST to /{bank_id}/messages instead
+            # Wrap send to rewrite the SSE endpoint URL to include bank_id if using path-based routing
            async def send_wrapper(message):
                if message["type"] == "http.response.body":
                    body = message.get("body", b"")
@@ -211,9 +356,10 @@ def create_mcp_app(memory: MemoryEngine):
    """
    Create an ASGI app that handles MCP requests.

-    URL pattern: /mcp/{bank_id}/
-
-    The bank_id is extracted from the URL path and made available to tools.
+    Bank ID can be provided via:
+    1. X-Bank-Id header: claude mcp add --transport http hindsight http://localhost:8888/mcp --header "X-Bank-Id: my-bank"
+    2. URL path: /mcp/{bank_id}/
+    3. Environment variable HINDSIGHT_MCP_BANK_ID (fallback, default: "default")

    Args:
        memory: MemoryEngine instance
@@ -8,6 +8,11 @@ import logging
 import os
 from dataclasses import dataclass

+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__)

 # Environment variable names
@@ -16,45 +21,143 @@ ENV_LLM_PROVIDER = "HINDSIGHT_API_LLM_PROVIDER"
 ENV_LLM_API_KEY = "HINDSIGHT_API_LLM_API_KEY"
 ENV_LLM_MODEL = "HINDSIGHT_API_LLM_MODEL"
 ENV_LLM_BASE_URL = "HINDSIGHT_API_LLM_BASE_URL"
+ENV_LLM_MAX_CONCURRENT = "HINDSIGHT_API_LLM_MAX_CONCURRENT"
+ENV_LLM_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_COHERE_API_KEY = "HINDSIGHT_API_COHERE_API_KEY"
+ENV_EMBEDDINGS_COHERE_MODEL = "HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL"
+ENV_RERANKER_COHERE_MODEL = "HINDSIGHT_API_RERANKER_COHERE_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_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"

+# 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"
+
+# Background task processing
+ENV_TASK_BACKEND = "HINDSIGHT_API_TASK_BACKEND"
+ENV_TASK_BACKEND_MEMORY_BATCH_SIZE = "HINDSIGHT_API_TASK_BACKEND_MEMORY_BATCH_SIZE"
+ENV_TASK_BACKEND_MEMORY_BATCH_INTERVAL = "HINDSIGHT_API_TASK_BACKEND_MEMORY_BATCH_INTERVAL"
+
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
 DEFAULT_LLM_PROVIDER = "openai"
 DEFAULT_LLM_MODEL = "gpt-5-mini"
+DEFAULT_LLM_MAX_CONCURRENT = 32
+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"

 DEFAULT_HOST = "0.0.0.0"
 DEFAULT_PORT = 8888
 DEFAULT_LOG_LEVEL = "info"
+DEFAULT_WORKERS = 1
 DEFAULT_MCP_ENABLED = True
-DEFAULT_GRAPH_RETRIEVER = "bfs"  # Options: "bfs", "mpfp"
+DEFAULT_GRAPH_RETRIEVER = "link_expansion"  # Options: "link_expansion", "mpfp", "bfs"
+DEFAULT_MPFP_TOP_K_NEIGHBORS = 20  # Fan-out limit per node in MPFP graph traversal
+DEFAULT_RECALL_MAX_CONCURRENT = 32  # Max concurrent recall operations per worker
+DEFAULT_RECALL_CONNECTION_BUDGET = 4  # Max concurrent DB connections per recall operation
 DEFAULT_MCP_LOCAL_BANK_ID = "mcp"

+# 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
+
+# Background task processing
+DEFAULT_TASK_BACKEND = "memory"  # Options: "memory", "noop"
+DEFAULT_TASK_BACKEND_MEMORY_BATCH_SIZE = 10
+DEFAULT_TASK_BACKEND_MEMORY_BATCH_INTERVAL = 1.0  # seconds
+
 # Default MCP tool descriptions (can be customized via env vars)
 DEFAULT_MCP_RETAIN_DESCRIPTION = """Store important information to long-term memory.

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

-# Required embedding dimension for database schema
-EMBEDDING_DIMENSION = 384
+# Default embedding dimension (used by initial migration, adjusted at runtime)
+EMBEDDING_DIMENSION = DEFAULT_EMBEDDING_DIMENSION
+
+
+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


@dataclass
@@ -86,11 +201,24 @@ class HindsightConfig:
    # Database
    database_url: str

-    # LLM
+    # LLM (default, used as fallback for per-operation config)
    llm_provider: str
    llm_api_key: str | None
    llm_model: str
    llm_base_url: str | None
+    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
@@ -101,6 +229,9 @@ class HindsightConfig:
    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

    # Server
    host: str
@@ -110,11 +241,39 @@ class HindsightConfig:

    # Recall
    graph_retriever: str
+    mpfp_top_k_neighbors: int
+    recall_max_concurrent: int
+    recall_connection_budget: 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
+
+    # Background task processing
+    task_backend: str
+    task_backend_memory_batch_size: int
+    task_backend_memory_batch_interval: float
+
    @classmethod
    def from_env(cls) -> "HindsightConfig":
        """Create configuration from environment variables."""
@@ -126,6 +285,17 @@ class HindsightConfig:
            llm_api_key=os.getenv(ENV_LLM_API_KEY),
            llm_model=os.getenv(ENV_LLM_MODEL, DEFAULT_LLM_MODEL),
            llm_base_url=os.getenv(ENV_LLM_BASE_URL) or None,
+            llm_max_concurrent=int(os.getenv(ENV_LLM_MAX_CONCURRENT, str(DEFAULT_LLM_MAX_CONCURRENT))),
+            llm_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),
@@ -134,6 +304,11 @@ class HindsightConfig:
            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))),
            # Server
            host=os.getenv(ENV_HOST, DEFAULT_HOST),
            port=int(os.getenv(ENV_PORT, DEFAULT_PORT)),
@@ -141,9 +316,50 @@ class HindsightConfig:
            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))
+            ),
            # Optimization flags
            skip_llm_verification=os.getenv(ENV_SKIP_LLM_VERIFICATION, "false").lower() == "true",
            lazy_reranker=os.getenv(ENV_LAZY_RERANKER, "false").lower() == "true",
+            # Observation thresholds
+            observation_min_facts=int(os.getenv(ENV_OBSERVATION_MIN_FACTS, str(DEFAULT_OBSERVATION_MIN_FACTS))),
+            observation_top_entities=int(
+                os.getenv(ENV_OBSERVATION_TOP_ENTITIES, str(DEFAULT_OBSERVATION_TOP_ENTITIES))
+            ),
+            # Retain settings
+            retain_max_completion_tokens=int(
+                os.getenv(ENV_RETAIN_MAX_COMPLETION_TOKENS, str(DEFAULT_RETAIN_MAX_COMPLETION_TOKENS))
+            ),
+            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))),
+            # Background task processing
+            task_backend=os.getenv(ENV_TASK_BACKEND, DEFAULT_TASK_BACKEND),
+            task_backend_memory_batch_size=int(
+                os.getenv(ENV_TASK_BACKEND_MEMORY_BATCH_SIZE, str(DEFAULT_TASK_BACKEND_MEMORY_BATCH_SIZE))
+            ),
+            task_backend_memory_batch_interval=float(
+                os.getenv(ENV_TASK_BACKEND_MEMORY_BATCH_INTERVAL, str(DEFAULT_TASK_BACKEND_MEMORY_BATCH_INTERVAL))
+            ),
        )

    def get_llm_base_url(self) -> str:
@@ -156,6 +372,8 @@ class HindsightConfig:
            return "https://api.groq.com/openai/v1"
        elif provider == "ollama":
            return "http://localhost:11434/v1"
+        elif provider == "lmstudio":
+            return "http://localhost:1234/v1"
        else:
            return ""

@@ -183,11 +401,32 @@ class HindsightConfig:
        """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 current configuration from environment variables."""
-    return HindsightConfig.from_env()
+    """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
@@ -6,17 +6,32 @@ 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_RERANKER_COHERE_MODEL,
+    DEFAULT_RERANKER_FLASHRANK_CACHE_DIR,
+    DEFAULT_RERANKER_FLASHRANK_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_RERANKER_COHERE_MODEL,
+    ENV_RERANKER_FLASHRANK_CACHE_DIR,
+    ENV_RERANKER_FLASHRANK_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,
 )

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

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

@@ -70,25 +85,34 @@ 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.
    """

-    def __init__(self, model_name: str | None = None):
+    # 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):
        """
        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."""
+        """Load the cross-encoder model and initialize the executor."""
        if self._model is not None:
            return

@@ -100,14 +124,30 @@ 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")

-    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
+        # 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]:
        """
        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

@@ -116,7 +156,13 @@ class LocalSTCrossEncoder(CrossEncoderModel):
        """
        if self._model is None:
            raise RuntimeError("Reranker not initialized. Call initialize() first.")
-        scores = self._model.predict(pairs, show_progress_bar=False)
+
+        # 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),
+        )
        return scores.tolist() if hasattr(scores, "tolist") else list(scores)


@@ -128,13 +174,21 @@ 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 = 32,
+        batch_size: int = DEFAULT_RERANKER_TEI_BATCH_SIZE,
+        max_concurrent: int = DEFAULT_RERANKER_TEI_MAX_CONCURRENT,
        max_retries: int = 3,
        retry_delay: float = 0.5,
    ):
@@ -144,80 +198,237 @@ 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: 32)
+            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.
            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._client: httpx.Client | None = None
+        self._async_client: httpx.AsyncClient | 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"

-    def _request_with_retry(self, method: str, url: str, **kwargs) -> httpx.Response:
-        """Make an HTTP request with automatic retries on transient errors."""
-        import time
-
+    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."""
        last_error = None
        delay = self.retry_delay

-        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:
+        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:
                    last_error = e
-                    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
+                    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

        raise last_error

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

-        logger.info(f"Reranker: initializing TEI provider at {self.base_url}")
-        self._client = httpx.Client(timeout=self.timeout)
+        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)

        # Verify server is reachable and get model info
+        # Use a temporary semaphore for initialization
+        init_semaphore = asyncio.Semaphore(1)
        try:
-            response = self._request_with_retry("GET", f"{self.base_url}/info")
+            response = await self._async_request_with_retry(
+                self._async_client, init_semaphore, "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}")

-    def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
+    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]:
        """
        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,
+        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)
+            timeout: Request timeout in seconds (default: 60.0)
+        """
+        self.api_key = api_key
+        self.model = model
+        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")
+
+        logger.info(f"Reranker: initializing Cohere provider with model {self.model}")
+        self._client = cohere.Client(api_key=self.api_key, timeout=self.timeout)
+        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

@@ -230,54 +441,206 @@ class RemoteTEICrossEncoder(CrossEncoderModel):
        if not pairs:
            return []

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

-        # Process in batches
-        for i in range(0, len(pairs), self.batch_size):
-            batch = pairs[i : i + self.batch_size]
+    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))

-            # 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))
+        all_scores = [0.0] * len(pairs)

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

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

-                try:
-                    response = self._request_with_retry(
-                        "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
-                    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}")
-
-            all_scores.extend(batch_scores)
+            # 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

        return all_scores


+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)
+
+
 def create_cross_encoder_from_env() -> CrossEncoderModel:
    """
    Create a CrossEncoderModel instance based on environment variables.
@@ -293,10 +656,29 @@ 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'")
-        return RemoteTEICrossEncoder(base_url=url)
+        batch_size = int(os.environ.get(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE)))
+        max_concurrent = int(os.environ.get(ENV_RERANKER_TEI_MAX_CONCURRENT, str(DEFAULT_RERANKER_TEI_MAX_CONCURRENT)))
+        return RemoteTEICrossEncoder(base_url=url, batch_size=batch_size, max_concurrent=max_concurrent)
    elif provider == "local":
        model = os.environ.get(ENV_RERANKER_LOCAL_MODEL)
        model_name = model or DEFAULT_RERANKER_LOCAL_MODEL
-        return LocalSTCrossEncoder(model_name=model_name)
+        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)
+        return CohereCrossEncoder(api_key=api_key, model=model)
+    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 == "rrf":
+        return RRFPassthroughCrossEncoder()
    else:
-        raise ValueError(f"Unknown reranker provider: {provider}. Supported: 'local', 'tei'")
+        raise ValueError(
+            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei', 'cohere', 'flashrank', 'rrf'"
+        )
@@ -0,0 +1,284 @@
+"""
+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,11 +83,22 @@ 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.

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

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

 from ..config import (
+    DEFAULT_EMBEDDINGS_COHERE_MODEL,
    DEFAULT_EMBEDDINGS_LOCAL_MODEL,
+    DEFAULT_EMBEDDINGS_OPENAI_MODEL,
    DEFAULT_EMBEDDINGS_PROVIDER,
-    EMBEDDING_DIMENSION,
+    ENV_COHERE_API_KEY,
+    ENV_EMBEDDINGS_COHERE_MODEL,
    ENV_EMBEDDINGS_LOCAL_MODEL,
+    ENV_EMBEDDINGS_OPENAI_API_KEY,
+    ENV_EMBEDDINGS_OPENAI_MODEL,
    ENV_EMBEDDINGS_PROVIDER,
    ENV_EMBEDDINGS_TEI_URL,
+    ENV_LLM_API_KEY,
 )

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

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

    @property
@@ -41,6 +47,12 @@ 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:
        """
@@ -54,13 +66,13 @@ class Embeddings(ABC):
    @abstractmethod
    def encode(self, texts: list[str]) -> list[list[float]]:
        """
-        Generate 384-dimensional embeddings for a list of texts.
+        Generate embeddings for a list of texts.

        Args:
            texts: List of text strings to encode

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

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

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

    def __init__(self, model_name: str | None = None):
@@ -81,16 +91,22 @@ 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:
@@ -112,26 +128,18 @@ class LocalSTEmbeddings(Embeddings):
            model_kwargs={"low_cpu_mem_usage": False, "device_map": None},
        )

-        # 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})")
+        self._dimension = self._model.get_sentence_embedding_dimension()
+        logger.info(f"Embeddings: local provider initialized (dim: {self._dimension})")

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

        Args:
            texts: List of text strings to encode

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

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

    def __init__(
@@ -174,11 +182,18 @@ 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
@@ -229,7 +244,24 @@ 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")
-            logger.info(f"Embeddings: TEI provider initialized (model: {self._model_id})")
+
+            # 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})")
        except httpx.HTTPError as e:
            raise RuntimeError(f"Failed to connect to TEI server at {self.base_url}: {e}")

@@ -269,6 +301,234 @@ 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,
+        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)
+            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.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")
+
+        logger.info(f"Embeddings: initializing OpenAI provider with model {self.model}")
+        self._client = OpenAI(api_key=self.api_key, max_retries=self.max_retries)
+
+        # 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,
+        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)
+            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.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")
+
+        logger.info(f"Embeddings: initializing Cohere provider with model {self.model}")
+        self._client = cohere.Client(api_key=self.api_key, timeout=self.timeout)
+
+        # 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
+
+
 def create_embeddings_from_env() -> Embeddings:
    """
    Create an Embeddings instance based on environment variables.
@@ -289,5 +549,21 @@ 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)
+        return OpenAIEmbeddings(api_key=api_key, model=model)
+    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)
+        return CohereEmbeddings(api_key=api_key, model=model)
    else:
-        raise ValueError(f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei'")
+        raise ValueError(f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei', 'openai', 'cohere'")
@@ -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
+            # For duplicates, we only insert once and reuse the ID, but track the count
            unique_entities = {}  # lowercase_name -> (entity_data, event_date, [indices])
            for idx, entity_data, event_date in entities_to_create:
                name_lower = entity_data["text"].lower()
@@ -223,29 +223,32 @@ 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
-            # This is much faster than individual inserts
+            # Uses the batch count for mention_count instead of always 1
            rows = await conn.fetch(
                f"""
                INSERT INTO {fq_table("entities")} (bank_id, canonical_name, first_seen, last_seen, mention_count)
-                SELECT $1, name, event_date, event_date, 1
-                FROM unnest($2::text[], $3::timestamptz[]) AS t(name, event_date)
+                SELECT $1, name, event_date, event_date, cnt
+                FROM unnest($2::text[], $3::timestamptz[], $4::int[]) AS t(name, event_date, cnt)
                ON CONFLICT (bank_id, LOWER(canonical_name))
                DO UPDATE SET
-                    mention_count = {fq_table("entities")}.mention_count + 1,
+                    mention_count = {fq_table("entities")}.mention_count + EXCLUDED.mention_count,
                    last_seen = EXCLUDED.last_seen
                RETURNING id
                """,
                bank_id,
                entity_names,
                entity_dates,
+                entity_counts,
            )

            # Map returned IDs back to original indices
@@ -110,6 +110,8 @@ class MemoryEngineInterface(ABC):
        *,
        budget: "Budget | None" = None,
        context: str | None = None,
+        max_tokens: int = 4096,
+        response_schema: dict | None = None,
        request_context: "RequestContext",
    ) -> "ReflectResult":
        """
@@ -120,6 +122,8 @@ class MemoryEngineInterface(ABC):
            query: The question to reflect on.
            budget: Search budget for retrieving context.
            context: Additional context for the reflection.
+            max_tokens: Maximum tokens for the response.
+            response_schema: Optional JSON Schema for structured output.
            request_context: Request context for authentication.

        Returns:
@@ -285,6 +289,7 @@ class MemoryEngineInterface(ABC):
        bank_id: str,
        *,
        fact_type: str | None = None,
+        limit: int = 1000,
        request_context: "RequestContext",
    ) -> dict[str, Any]:
        """
@@ -293,10 +298,11 @@ 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.
+            Dict with nodes, edges, table_rows, total_units, limit.
        """
        ...

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

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

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

@@ -6,6 +6,7 @@ import asyncio
 import json
 import logging
 import os
+import re
 import time
 from typing import Any

@@ -15,6 +16,16 @@ from google.genai import errors as genai_errors
 from google.genai import types as genai_types
 from openai import APIConnectionError, APIStatusError, AsyncOpenAI, LengthFinishReasonError

+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

@@ -24,7 +35,9 @@ logger = logging.getLogger(__name__)
 logging.getLogger("httpx").setLevel(logging.WARNING)

 # Global semaphore to limit concurrent LLM requests across all instances
-_global_llm_semaphore = asyncio.Semaphore(32)
+# Set HINDSIGHT_API_LLM_MAX_CONCURRENT=1 for local LLMs (LM Studio, Ollama)
+_llm_max_concurrent = int(os.getenv(ENV_LLM_MAX_CONCURRENT, str(DEFAULT_LLM_MAX_CONCURRENT)))
+_global_llm_semaphore = asyncio.Semaphore(_llm_max_concurrent)


 class OutputTooLongError(Exception):
@@ -53,53 +66,87 @@ class LLMProvider:
        base_url: str,
        model: str,
        reasoning_effort: str = "low",
+        groq_service_tier: str | None = None,
    ):
        """
        Initialize LLM provider.

        Args:
-            provider: Provider name ("openai", "groq", "ollama", "gemini").
+            provider: Provider name ("openai", "groq", "ollama", "gemini", "anthropic", "lmstudio").
            api_key: API key.
            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"]
+        valid_providers = ["openai", "groq", "ollama", "gemini", "anthropic", "lmstudio", "mock"]
        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":
                self.base_url = "https://api.groq.com/openai/v1"
            elif self.provider == "ollama":
                self.base_url = "http://localhost:11434/v1"
+            elif self.provider == "lmstudio":
+                self.base_url = "http://localhost:1234/v1"

-        # Validate API key (not needed for ollama)
-        if self.provider != "ollama" and not self.api_key:
+        # Validate API key (not needed for ollama, lmstudio, or mock)
+        if self.provider not in ("ollama", "lmstudio", "mock") 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)
+        self.timeout = float(os.getenv(ENV_LLM_TIMEOUT, str(DEFAULT_LLM_TIMEOUT)))
+
        # Create client based on provider
-        if self.provider == "gemini":
+        self._client = None
+        self._gemini_client = None
+        self._anthropic_client = None
+
+        if self.provider == "mock":
+            # Mock provider - no client needed
+            pass
+        elif self.provider == "gemini":
            self._gemini_client = genai.Client(api_key=self.api_key)
-            self._client = None
-        elif self.provider == "ollama":
-            self._client = AsyncOpenAI(api_key="ollama", base_url=self.base_url, max_retries=0)
-            self._gemini_client = None
+        elif self.provider == "anthropic":
+            from anthropic import AsyncAnthropic
+
+            # Only pass base_url if it's set (Anthropic uses default URL otherwise)
+            anthropic_kwargs = {"api_key": self.api_key}
+            if self.base_url:
+                anthropic_kwargs["base_url"] = self.base_url
+            if self.timeout:
+                anthropic_kwargs["timeout"] = self.timeout
+            self._anthropic_client = AsyncAnthropic(**anthropic_kwargs)
+        elif self.provider in ("ollama", "lmstudio"):
+            # Use dummy key if not provided for local
+            api_key = self.api_key or "local"
+            client_kwargs = {"api_key": api_key, "base_url": self.base_url, "max_retries": 0}
+            if self.timeout:
+                client_kwargs["timeout"] = self.timeout
+            self._client = AsyncOpenAI(**client_kwargs)
        else:
            # Only pass base_url if it's set (OpenAI uses default URL otherwise)
            client_kwargs = {"api_key": self.api_key, "max_retries": 0}
            if self.base_url:
                client_kwargs["base_url"] = self.base_url
-            self._client = AsyncOpenAI(**client_kwargs)  # type: ignore[invalid-argument-type] - dict kwargs
-            self._gemini_client = None
+            if self.timeout:
+                client_kwargs["timeout"] = self.timeout
+            self._client = AsyncOpenAI(**client_kwargs)

    async def verify_connection(self) -> None:
        """
@@ -135,6 +182,8 @@ class LLMProvider:
        initial_backoff: float = 1.0,
        max_backoff: float = 60.0,
        skip_validation: bool = False,
+        strict_schema: bool = False,
+        return_usage: bool = False,
    ) -> Any:
        """
        Make an LLM API call with retry logic.
@@ -149,21 +198,60 @@ class LLMProvider:
            initial_backoff: Initial backoff time in seconds.
            max_backoff: Maximum backoff time in seconds.
            skip_validation: Return raw JSON without Pydantic validation.
+            strict_schema: Use strict JSON schema enforcement (OpenAI only). Guarantees all required fields.
+            return_usage: If True, return tuple (result, TokenUsage) instead of just result.

        Returns:
-            Parsed response if response_format is provided, otherwise text content.
+            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.

        Raises:
            OutputTooLongError: If output exceeds token limits.
            Exception: Re-raises API errors after retries exhausted.
        """
+        queue_start_time = time.time()
        async with _global_llm_semaphore:
            start_time = time.time()
+            semaphore_wait_time = start_time - queue_start_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
+                    messages,
+                    response_format,
+                    max_retries,
+                    initial_backoff,
+                    max_backoff,
+                    skip_validation,
+                    start_time,
+                    scope,
+                    return_usage,
+                    semaphore_wait_time,
+                )
+
+            # Handle Anthropic provider separately
+            if self.provider == "anthropic":
+                return await self._call_anthropic(
+                    messages,
+                    response_format,
+                    max_completion_tokens,
+                    max_retries,
+                    initial_backoff,
+                    max_backoff,
+                    skip_validation,
+                    start_time,
+                    scope,
+                    return_usage,
+                    semaphore_wait_time,
                )

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

            call_params = {
@@ -215,58 +306,108 @@ class LLMProvider:
            # Provider-specific parameters
            if self.provider == "groq":
                call_params["seed"] = DEFAULT_LLM_SEED
-                extra_body = {"service_tier": "auto"}
-                # Only add reasoning parameters for reasoning models
+                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
                if is_reasoning_model:
                    extra_body["include_reasoning"] = False
-                call_params["extra_body"] = extra_body
+                if extra_body:
+                    call_params["extra_body"] = extra_body

            last_exception = None

            for attempt in range(max_retries + 1):
                try:
                    if response_format is not None:
-                        # Add schema to system message for JSON mode
+                        schema = None
                        if hasattr(response_format, "model_json_schema"):
                            schema = response_format.model_json_schema()
-                            schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"

-                            if 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 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)}"

-                        call_params["response_format"] = {"type": "json_object"}
+                                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

-                        # Log raw LLM response for debugging JSON parse issues
-                        try:
-                            json_data = json.loads(content)
-                        except json.JSONDecodeError as json_err:
-                            # Truncate content for logging (first 500 and last 200 chars)
-                            content_preview = content[:500] if content else "<empty>"
-                            if content and len(content) > 700:
-                                content_preview = f"{content[:500]}...TRUNCATED...{content[-200:]}"
-                            logger.warning(
-                                f"JSON parse error from LLM response (attempt {attempt + 1}/{max_retries + 1}): {json_err}\n"
-                                f"  Model: {self.provider}/{self.model}\n"
-                                f"  Content length: {len(content) if content else 0} chars\n"
-                                f"  Content preview: {content_preview!r}\n"
-                                f"  Finish reason: {response.choices[0].finish_reason if response.choices else 'unknown'}"
-                            )
-                            # Retry on JSON parse errors - LLM may return valid JSON on next attempt
-                            if attempt < max_retries:
-                                backoff = min(initial_backoff * (2**attempt), max_backoff)
-                                await asyncio.sleep(backoff)
-                                last_exception = json_err
-                                continue
-                            else:
-                                logger.error(f"JSON parse error after {max_retries + 1} attempts, giving up")
-                                raise
+                        # Strip reasoning model thinking tags
+                        # Supports: <think>, <thinking>, <reasoning>, |startthink|/|endthink|
+                        # for reasoning models that embed thinking in their output (e.g., Qwen3, DeepSeek)
+                        if content:
+                            original_len = len(content)
+                            content = re.sub(r"<think>.*?</think>", "", content, flags=re.DOTALL)
+                            content = re.sub(r"<thinking>.*?</thinking>", "", content, flags=re.DOTALL)
+                            content = re.sub(r"<reasoning>.*?</reasoning>", "", content, flags=re.DOTALL)
+                            content = re.sub(r"\|startthink\|.*?\|endthink\|", "", content, flags=re.DOTALL)
+                            content = content.strip()
+                            if len(content) < original_len:
+                                logger.debug(f"Stripped {original_len - len(content)} chars of reasoning tokens")
+
+                        # For local models, they may wrap JSON in markdown code blocks
+                        if self.provider in ("lmstudio", "ollama"):
+                            clean_content = content
+                            if "```json" in content:
+                                clean_content = content.split("```json")[1].split("```")[0].strip()
+                            elif "```" in content:
+                                clean_content = content.split("```")[1].split("```")[0].strip()
+                            try:
+                                json_data = json.loads(clean_content)
+                            except json.JSONDecodeError:
+                                # Fallback to parsing raw content
+                                json_data = json.loads(content)
+                        else:
+                            # Log raw LLM response for debugging JSON parse issues
+                            try:
+                                json_data = json.loads(content)
+                            except json.JSONDecodeError as json_err:
+                                # Truncate content for logging (first 500 and last 200 chars)
+                                content_preview = content[:500] if content else "<empty>"
+                                if content and len(content) > 700:
+                                    content_preview = f"{content[:500]}...TRUNCATED...{content[-200:]}"
+                                logger.warning(
+                                    f"JSON parse error from LLM response (attempt {attempt + 1}/{max_retries + 1}): {json_err}\n"
+                                    f"  Model: {self.provider}/{self.model}\n"
+                                    f"  Content length: {len(content) if content else 0} chars\n"
+                                    f"  Content preview: {content_preview!r}\n"
+                                    f"  Finish reason: {response.choices[0].finish_reason if response.choices else 'unknown'}"
+                                )
+                                # Retry on JSON parse errors - LLM may return valid JSON on next attempt
+                                if attempt < max_retries:
+                                    backoff = min(initial_backoff * (2**attempt), max_backoff)
+                                    await asyncio.sleep(backoff)
+                                    last_exception = json_err
+                                    continue
+                                else:
+                                    logger.error(f"JSON parse error after {max_retries + 1} attempts, giving up")
+                                    raise

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

-                    # Log slow calls
+                    # Record token usage metrics
                    duration = time.time() - start_time
                    usage = response.usage
-                    if duration > 10.0:
-                        ratio = max(1, usage.completion_tokens) / usage.prompt_tokens
+                    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)
                        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: 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}"
+                            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}"
                        )

+                    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:
@@ -339,6 +505,168 @@ class LLMProvider:
                raise last_exception
            raise RuntimeError("LLM call failed after all retries with no exception captured")

+    async def _call_anthropic(
+        self,
+        messages: list[dict[str, str]],
+        response_format: Any | None,
+        max_completion_tokens: int | None,
+        max_retries: int,
+        initial_backoff: float,
+        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
+
+        # Convert OpenAI-style messages to Anthropic format
+        system_prompt = None
+        anthropic_messages = []
+
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+
+            if role == "system":
+                if system_prompt:
+                    system_prompt += "\n\n" + content
+                else:
+                    system_prompt = content
+            else:
+                anthropic_messages.append({"role": role, "content": content})
+
+        # Add JSON schema instruction if response_format is provided
+        if response_format is not None and hasattr(response_format, "model_json_schema"):
+            schema = response_format.model_json_schema()
+            schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
+            if system_prompt:
+                system_prompt += schema_msg
+            else:
+                system_prompt = schema_msg
+
+        # Prepare parameters
+        call_params = {
+            "model": self.model,
+            "messages": anthropic_messages,
+            "max_tokens": max_completion_tokens if max_completion_tokens is not None else 4096,
+        }
+
+        if system_prompt:
+            call_params["system"] = system_prompt
+
+        last_exception = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                response = await self._anthropic_client.messages.create(**call_params)
+
+                # Anthropic response content is a list of blocks
+                content = ""
+                for block in response.content:
+                    if block.type == "text":
+                        content += block.text
+
+                if response_format is not None:
+                    # Models may wrap JSON in markdown code blocks
+                    clean_content = content
+                    if "```json" in content:
+                        clean_content = content.split("```json")[1].split("```")[0].strip()
+                    elif "```" in content:
+                        clean_content = content.split("```")[1].split("```")[0].strip()
+
+                    try:
+                        json_data = json.loads(clean_content)
+                    except json.JSONDecodeError:
+                        # Fallback to parsing raw content if markdown stripping failed
+                        json_data = json.loads(content)
+
+                    if skip_validation:
+                        result = json_data
+                    else:
+                        result = response_format.model_validate(json_data)
+                else:
+                    result = content
+
+                # Record metrics and log slow calls
+                duration = time.time() - start_time
+                input_tokens = response.usage.input_tokens or 0 if response.usage else 0
+                output_tokens = response.usage.output_tokens or 0 if response.usage else 0
+                total_tokens = input_tokens + output_tokens
+
+                # Record LLM metrics
+                metrics = get_metrics_collector()
+                metrics.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    duration=duration,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    success=True,
+                )
+
+                # Log slow calls
+                if duration > 10.0:
+                    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"time={duration:.3f}s{wait_info}"
+                    )
+
+                if return_usage:
+                    token_usage = TokenUsage(
+                        input_tokens=input_tokens,
+                        output_tokens=output_tokens,
+                        total_tokens=total_tokens,
+                    )
+                    return result, token_usage
+                return result
+
+            except json.JSONDecodeError as e:
+                last_exception = e
+                if attempt < max_retries:
+                    logger.warning("Anthropic returned invalid JSON, retrying...")
+                    backoff = min(initial_backoff * (2**attempt), max_backoff)
+                    await asyncio.sleep(backoff)
+                    continue
+                else:
+                    logger.error(f"Anthropic returned invalid JSON after {max_retries + 1} attempts")
+                    raise
+
+            except (APIConnectionError, RateLimitError, APIStatusError) as e:
+                # Fast fail on 401/403
+                if isinstance(e, APIStatusError) and e.status_code in (401, 403):
+                    logger.error(f"Anthropic auth error (HTTP {e.status_code}), not retrying: {str(e)}")
+                    raise
+
+                last_exception = e
+                if attempt < max_retries:
+                    # Check if it's a rate limit or server error
+                    should_retry = isinstance(e, (APIConnectionError, RateLimitError)) or (
+                        isinstance(e, APIStatusError) and e.status_code >= 500
+                    )
+
+                    if should_retry:
+                        backoff = min(initial_backoff * (2**attempt), max_backoff)
+                        jitter = backoff * 0.2 * (2 * (time.time() % 1) - 1)
+                        await asyncio.sleep(backoff + jitter)
+                        continue
+
+                logger.error(f"Anthropic API error after {max_retries + 1} attempts: {str(e)}")
+                raise
+
+            except Exception as e:
+                logger.error(f"Unexpected error during Anthropic call: {type(e).__name__}: {str(e)}")
+                raise
+
+        if last_exception:
+            raise last_exception
+        raise RuntimeError("Anthropic call failed after all retries")
+
    async def _call_ollama_native(
        self,
        messages: list[dict[str, str]],
@@ -350,6 +678,9 @@ 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.
@@ -424,11 +755,39 @@ 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:
-                        return json_data
+                        validated_result = json_data
                    else:
-                        return response_format.model_validate(json_data)
+                        validated_result = response_format.model_validate(json_data)
+
+                    if return_usage:
+                        token_usage = TokenUsage(
+                            input_tokens=input_tokens,
+                            output_tokens=output_tokens,
+                            total_tokens=total_tokens,
+                        )
+                        return validated_result, token_usage
+                    return validated_result

                except httpx.HTTPStatusError as e:
                    last_exception = e
@@ -471,6 +830,9 @@ 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
@@ -547,16 +909,43 @@ class LLMProvider:
                else:
                    result = content

-                # Log slow calls
+                # Record metrics and log slow calls
                duration = time.time() - start_time
-                if duration > 10.0 and hasattr(response, "usage_metadata") and response.usage_metadata:
+                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 ""
                    logger.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"
+                        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}"
                    )

+                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:
@@ -598,6 +987,61 @@ 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."""
@@ -84,7 +84,7 @@ class DateparserQueryAnalyzer(QueryAnalyzer):

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

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

@@ -123,6 +121,9 @@ 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,
@@ -14,6 +14,37 @@ from pydantic import BaseModel, ConfigDict, Field
 VALID_RECALL_FACT_TYPES = frozenset(["world", "experience", "opinion"])


+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,
+        )
+
+
 class DispositionTraits(BaseModel):
    """
    Disposition traits for a memory bank.
@@ -54,6 +85,7 @@ class MemoryFact(BaseModel):
                "metadata": {"source": "slack"},
                "chunk_id": "bank123_session_abc123_0",
                "activation": 0.95,
+                "tags": ["user_a", "session_123"],
            }
        }
    )
@@ -71,6 +103,7 @@ 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):
@@ -123,7 +156,8 @@ class ReflectResult(BaseModel):
    Result from a reflect operation.

    Contains the formulated answer, the facts it was based on (organized by type),
-    and any new opinions that were formed during the reflection process.
+    any new opinions that were formed during the reflection process, and optionally
+    structured output if a response schema was provided.
    """

    model_config = ConfigDict(
@@ -145,6 +179,8 @@ class ReflectResult(BaseModel):
                    "opinion": [],
                },
                "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},
            }
        }
    )
@@ -154,6 +190,14 @@ class ReflectResult(BaseModel):
        description="Facts used to formulate the answer, organized by type (world, experience, opinion)"
    )
    new_opinions: list[str] = Field(default_factory=list, description="List of newly formed opinions during reflection")
+    structured_output: dict[str, Any] | None = Field(
+        default=None,
+        description="Structured output parsed according to the provided response schema. Only present when response_schema was provided.",
+    )
+    usage: TokenUsage | None = Field(
+        default=None,
+        description="Token usage metrics for the LLM calls made during this reflect operation.",
+    )


 class Opinion(BaseModel):
@@ -13,16 +13,23 @@ logger = logging.getLogger(__name__)


 async def process_entities_batch(
-    entity_resolver, conn, bank_id: str, unit_ids: list[str], facts: list[ProcessedFact], log_buffer: list[str] = None
+    entity_resolver,
+    conn,
+    bank_id: str,
+    unit_ids: list[str],
+    facts: list[ProcessedFact],
+    log_buffer: list[str] = None,
+    user_entities_per_content: dict[int, list[dict]] = None,
 ) -> list[EntityLink]:
    """
    Process entities for all facts and create entity links.

    This function:
    1. Extracts entity mentions from fact texts
-    2. Resolves entity names to canonical entities
-    3. Creates entity records in the database
-    4. Returns entity links ready for insertion
+    2. Merges user-provided entities with LLM-extracted entities
+    3. Resolves entity names to canonical entities
+    4. Creates entity records in the database
+    5. Returns entity links ready for insertion

    Args:
        entity_resolver: EntityResolver instance for entity resolution
@@ -31,6 +38,7 @@ async def process_entities_batch(
        unit_ids: List of unit IDs (same length as facts)
        facts: List of ProcessedFact objects
        log_buffer: Optional buffer for detailed logging
+        user_entities_per_content: Dict mapping content_index to list of user-provided entities

    Returns:
        List of EntityLink objects for batch insertion
@@ -41,14 +49,35 @@ async def process_entities_batch(
    if len(unit_ids) != len(facts):
        raise ValueError(f"Mismatch between unit_ids ({len(unit_ids)}) and facts ({len(facts)})")

+    user_entities_per_content = user_entities_per_content or {}
+
    # Extract data for link_utils function
    fact_texts = [fact.fact_text for fact in facts]
    # Use occurred_start if available, otherwise use mentioned_at for entity timestamps
    fact_dates = [fact.occurred_start if fact.occurred_start is not None else fact.mentioned_at for fact in facts]
-    # Convert EntityRef objects to dict format expected by link_utils
-    entities_per_fact = [
-        [{"text": entity.name, "type": "CONCEPT"} for entity in (fact.entities or [])] for fact in facts
-    ]
+
+    # Convert EntityRef objects to dict format and merge with user-provided entities
+    entities_per_fact = []
+    for fact in facts:
+        # Start with LLM-extracted entities
+        llm_entities = [{"text": entity.name, "type": "CONCEPT"} for entity in (fact.entities or [])]
+
+        # Get user entities for this content (use content_index from fact)
+        user_entities = user_entities_per_content.get(fact.content_index, [])
+
+        # Merge with case-insensitive deduplication
+        seen_texts = {e["text"].lower() for e in llm_entities}
+        for user_entity in user_entities:
+            if user_entity["text"].lower() not in seen_texts:
+                llm_entities.append(
+                    {
+                        "text": user_entity["text"],
+                        "type": user_entity.get("type", "CONCEPT"),
+                    }
+                )
+                seen_texts.add(user_entity["text"].lower())
+
+        entities_per_fact.append(llm_entities)

    # Use existing link_utils function for entity processing
    entity_links = await link_utils.extract_entities_batch_optimized(
@@ -14,7 +14,47 @@ 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:
+    """
+    Infer a temporal date from fact text when LLM didn't provide occurred_start.
+
+    This is a fallback for when the LLM fails to extract temporal information
+    from relative time expressions like "last night", "yesterday", etc.
+    """
+    import re
+
+    fact_lower = fact_text.lower()
+
+    # Map relative time expressions to day offsets
+    temporal_patterns = {
+        r"\blast night\b": -1,
+        r"\byesterday\b": -1,
+        r"\btoday\b": 0,
+        r"\bthis morning\b": 0,
+        r"\bthis afternoon\b": 0,
+        r"\bthis evening\b": 0,
+        r"\btonigh?t\b": 0,
+        r"\btomorrow\b": 1,
+        r"\blast week\b": -7,
+        r"\bthis week\b": 0,
+        r"\bnext week\b": 7,
+        r"\blast month\b": -30,
+        r"\bthis month\b": 0,
+        r"\bnext month\b": 30,
+    }
+
+    for pattern, offset_days in temporal_patterns.items():
+        if re.search(pattern, fact_lower):
+            target_date = event_date + timedelta(days=offset_days)
+            return target_date.replace(hour=0, minute=0, second=0, microsecond=0).isoformat()
+
+    # If no relative time expression found, return None
+    return None


 def _sanitize_text(text: str) -> str:
@@ -71,22 +111,44 @@ class Fact(BaseModel):


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

-    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."
-    )
-    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, "
-        "'enables' = this fact enables/allows the target fact, "
-        "'prevents' = this fact prevents/blocks the target fact"
+    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"
    )
    strength: float = Field(
-        description="Strength of causal relationship (0.0 to 1.0). "
-        "1.0 = direct/strong causation, 0.5 = moderate, 0.3 = weak/indirect",
+        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: "
+        "'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"
+    )
+    strength: float = Field(
+        description="Strength of relationship (0.0 to 1.0). 1.0 = strong, 0.5 = moderate",
        ge=0.0,
        le=1.0,
        default=1.0,
@@ -94,16 +156,67 @@ class CausalRelation(BaseModel):


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

    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="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"]},
+    )

    what: str = Field(
        description="WHAT happened - COMPLETE, DETAILED description with ALL specifics. "
@@ -146,16 +259,11 @@ class ExtractedFact(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.",
@@ -165,59 +273,76 @@ class ExtractedFact(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[CausalRelation] | None = Field(
-        default=None, description="Causal links to other facts. Can be null."
+
+    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.",
    )

    @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

-    @field_validator("causal_relations", mode="before")
+
+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")
    @classmethod
-    def ensure_causal_relations_list(cls, v):
-        """Ensure causal_relations is always a list (convert None to empty list)."""
+    def ensure_entities_list(cls, v):
        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}")
+class FactExtractionResponseNoCausal(BaseModel):
+    """Response for fact extraction without causal relations."""

-        # 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")
+    facts: list[ExtractedFactNoCausal] = Field(description="List of extracted factual statements")


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


-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).
+# =============================================================================
+# FACT EXTRACTION PROMPTS
+# =============================================================================

-    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 ""
+# 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.

-    # 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.
+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.

 {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
@@ -435,106 +640,88 @@ FACT TYPE
  Include: what the user asked, what problem they wanted solved, what context they provided

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

-ALWAYS extract user preferences as separate facts! Watch for these keywords:
- "enjoy", "like", "love", "prefer", "hate", "dislike", "favorite", "ideal", "dream", "want"
+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)

-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"]
+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 = """

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

-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
+Link facts with causal_relations (max 2 per fact). target_index must be < this fact's index.
+Types: "caused_by", "enabled_by", "prevented_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!
+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"}]"""

-══════════════════════════════════════════════════════════════════════════
-EXAMPLES
-══════════════════════════════════════════════════════════════════════════

-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!"
+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).

-Output facts:
+    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 ""

-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"]
+    # 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."
+        )

-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"]
+    # 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

-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"]
+    # Select base prompt based on extraction mode
+    if extraction_mode == "verbose":
+        base_prompt = VERBOSE_FACT_EXTRACTION_PROMPT
+    else:
+        base_prompt = CONCISE_FACT_EXTRACTION_PROMPT

-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%."
+    # Format the prompt with fact types instruction
+    prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)

-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"""
+    # 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

    import logging

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

+    usage = TokenUsage()  # Track cumulative usage across retries
    for attempt in range(max_retries):
        try:
-            extraction_response_json = await llm_config.call(
+            extraction_response_json, call_usage = await llm_config.call(
                messages=[{"role": "system", "content": prompt}, {"role": "user", "content": user_message}],
-                response_format=FactExtractionResponse,
+                response_format=response_schema,
                scope="memory_extract_facts",
                temperature=0.1,
-                max_completion_tokens=65000,
+                max_completion_tokens=config.retain_max_completion_tokens,
                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 = []
@@ -590,9 +780,10 @@ Text:
                        f"LLM returned non-dict JSON after {max_retries} attempts: {type(extraction_response_json).__name__}. "
                        f"Raw: {str(extraction_response_json)[:500]}"
                    )
-                    return []
+                    return [], usage

            raw_facts = extraction_response_json.get("facts", [])
+
            if not raw_facts:
                logger.debug(
                    f"LLM response missing 'facts' field or returned empty list. "
@@ -676,13 +867,18 @@ Text:
                if fact_kind == "event":
                    occurred_start = get_value("occurred_start")
                    occurred_end = get_value("occurred_end")
-                    if occurred_start:
+
+                    # If LLM didn't set temporal fields, try to extract them from the fact text
+                    if not occurred_start:
+                        fact_data["occurred_start"] = _infer_temporal_date(combined_text, event_date)
+                    else:
                        fact_data["occurred_start"] = occurred_start
-                        # For point events: if occurred_end not set, default to occurred_start
-                        if occurred_end:
-                            fact_data["occurred_end"] = occurred_end
-                        else:
-                            fact_data["occurred_end"] = occurred_start
+
+                    # For point events: if occurred_end not set, default to occurred_start
+                    if occurred_end:
+                        fact_data["occurred_end"] = occurred_end
+                    elif fact_data.get("occurred_start"):
+                        fact_data["occurred_end"] = fact_data["occurred_start"]

                # Add entities if present (validate as Entity objects)
                # LLM sometimes returns strings instead of {"text": "..."} format
@@ -702,17 +898,40 @@ Text:
                    if validated_entities:
                        fact_data["entities"] = validated_entities

-                # 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:
+                # Add per-fact causal relations (only if enabled in config)
+                if extract_causal_links:
                    validated_relations = []
-                    for rel in causal_relations:
-                        if isinstance(rel, dict) and "target_fact_index" in rel and "relation_type" in rel:
+                    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
+
                            try:
-                                validated_relations.append(CausalRelation.model_validate(rel))
+                                validated_relations.append(
+                                    CausalRelation(
+                                        target_fact_index=target_idx,
+                                        relation_type=relation_type,
+                                        strength=strength,
+                                    )
+                                )
                            except Exception as e:
-                                logger.warning(f"Invalid causal relation {rel}: {e}")
+                                logger.debug(f"Invalid causal relation {rel}: {e}")
+
                    if validated_relations:
                        fact_data["causal_relations"] = validated_relations

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

-            return chunk_facts
+            return chunk_facts, usage

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

@@ -780,7 +999,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:
-        List of fact dictionaries extracted from the chunk (possibly from sub-chunks)
+        Tuple of (facts list, token usage) extracted from the chunk (possibly from sub-chunks)
    """
    import logging

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

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

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

-        return all_facts
+        return all_facts, total_usage


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

@@ -893,11 +1114,22 @@ 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) where:
+        Tuple of (facts, chunks, usage) 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
    """
-    chunks = chunk_text(text, max_chars=3000)
+    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"
+        )
+
    tasks = [
        _extract_facts_with_auto_split(
            chunk=chunk,
@@ -914,10 +1146,12 @@ async def extract_facts_from_text(
    chunk_results = await asyncio.gather(*tasks)
    all_facts = []
    chunk_metadata = []  # [(chunk_text, fact_count), ...]
-    for chunk, chunk_facts in zip(chunks, chunk_results):
+    total_usage = TokenUsage()
+    for chunk, (chunk_facts, chunk_usage) in zip(chunks, chunk_results):
        all_facts.extend(chunk_facts)
        chunk_metadata.append((chunk, len(chunk_facts)))
-    return all_facts, chunk_metadata
+        total_usage = total_usage + chunk_usage
+    return all_facts, chunk_metadata, total_usage


 # ============================================================================
@@ -938,7 +1172,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]]:
+) -> tuple[list[ExtractedFactType], list[ChunkMetadata], TokenUsage]:
    """
    Extract facts from multiple content items in parallel.

@@ -955,10 +1189,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)
+        Tuple of (extracted_facts, chunks_metadata, usage)
    """
    if not contents:
-        return [], []
+        return [], [], TokenUsage()

    # Step 1: Create parallel fact extraction tasks
    fact_extraction_tasks = []
@@ -981,11 +1215,15 @@ 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)) in enumerate(zip(contents, all_fact_results)):
+    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
        chunk_start_idx = global_chunk_idx

        # Convert chunk tuples to ChunkMetadata objects
@@ -1030,6 +1268,7 @@ 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)
@@ -1039,7 +1278,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
+    return extracted_facts, chunks_metadata, total_usage


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

    for fact in facts:
        fact_texts.append(fact.fact_text)
@@ -65,16 +66,31 @@ 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"""
-        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)
-        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[]
+        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
        RETURNING id
        """,
        bank_id,
@@ -91,6 +107,7 @@ async def insert_facts_batch(
        metadata_jsons,
        chunk_ids,
        document_ids,
+        tags_list,
    )

    unit_ids = [str(row["id"]) for row in results]
@@ -121,7 +138,13 @@ 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
+    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,
 ) -> None:
    """
    Handle document tracking in the database.
@@ -133,6 +156,7 @@ 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

@@ -149,13 +173,14 @@ 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)
-        VALUES ($1, $2, $3, $4, $5, $6)
+        INSERT INTO {fq_table("documents")} (id, bank_id, original_text, content_hash, metadata, retain_params, tags)
+        VALUES ($1, $2, $3, $4, $5, $6, $7)
        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,
@@ -164,4 +189,5 @@ 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,14 +479,18 @@ async def create_temporal_links_batch_per_fact(

        if links:
            insert_start = time_mod.time()
-            await conn.executemany(
-                f"""
-                INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
-                VALUES ($1, $2, $3, $4, $5)
-                ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
-                """,
-                links,
-            )
+            # Batch 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,
+                )
            _log(log_buffer, f"      [7.4] Insert {len(links)} temporal links: {time_mod.time() - insert_start:.3f}s")

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

        if all_links:
            insert_start = time_mod.time()
-            await conn.executemany(
-                f"""
-                INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
-                VALUES ($1, $2, $3, $4, $5)
-                ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
-                """,
-                all_links,
-            )
+            # Batch 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,
+                )
            _log(
                log_buffer, f"      [8.3] Insert {len(all_links)} semantic links: {time_mod.time() - insert_start:.3f}s"
            )
@@ -9,6 +9,7 @@ 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
@@ -49,8 +50,9 @@ async def regenerate_observations_batch(
        entity_links: Entity links from this batch
        log_buffer: Optional log buffer for timing
    """
-    TOP_N_ENTITIES = 5
-    MIN_FACTS_THRESHOLD = 5
+    config = get_config()
+    TOP_N_ENTITIES = config.observation_top_entities
+    MIN_FACTS_THRESHOLD = config.observation_min_facts

    if not entity_links:
        return
@@ -9,6 +9,7 @@ import time
 import uuid
 from datetime import UTC, datetime

+from ...config import get_config
 from ..db_utils import acquire_with_retry
 from . import bank_utils

@@ -18,6 +19,7 @@ def utcnow():
    return datetime.now(UTC)


+from ..response_models import TokenUsage
 from . import (
    chunk_storage,
    deduplication,
@@ -47,7 +49,8 @@ async def retain_batch(
    is_first_batch: bool = True,
    fact_type_override: str | None = None,
    confidence_score: float | None = None,
-) -> list[list[str]]:
+    document_tags: list[str] | None = None,
+) -> tuple[list[list[str]], TokenUsage]:
    """
    Process a batch of content through the retain pipeline.

@@ -65,9 +68,10 @@ 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:
-        List of unit ID lists (one list per content item)
+        Tuple of (unit ID lists, token usage for fact extraction)
    """
    start_time = time.time()
    total_chars = sum(len(item.get("content", "")) for item in contents_dicts)
@@ -86,11 +90,16 @@ 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)

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

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

        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]
+        return [[] for _ in contents], usage

    # Apply fact_type_override if provided
    if fact_type_override:
@@ -222,7 +231,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
+                    conn, bank_id, document_id, combined_content, is_first_batch, retain_params, document_tags
                )
                document_ids_added.append(document_id)
                doc_id_mapping[None] = document_id  # For backwards compatibility
@@ -266,7 +275,13 @@ 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
+                                conn,
+                                bank_id,
+                                actual_doc_id,
+                                combined_content,
+                                is_first_batch,
+                                retain_params,
+                                document_tags,
                            )
                            document_ids_added.append(actual_doc_id)

@@ -343,7 +358,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]
+                return [[] for _ in contents], usage

            # Insert facts (document_id is now stored per-fact)
            step_start = time.time()
@@ -352,8 +367,18 @@ async def retain_batch(

            # Process entities
            step_start = time.time()
+            # Build map of content_index -> user entities for merging
+            user_entities_per_content = {
+                idx: content.entities for idx, content in enumerate(contents) if content.entities
+            }
            entity_links = await entity_processing.process_entities_batch(
-                entity_resolver, conn, bank_id, unit_ids, non_duplicate_facts, log_buffer
+                entity_resolver,
+                conn,
+                bank_id,
+                unit_ids,
+                non_duplicate_facts,
+                log_buffer,
+                user_entities_per_content=user_entities_per_content,
            )
            log_buffer.append(f"[6] Process entities: {len(entity_links)} links in {time.time() - step_start:.3f}s")

@@ -383,16 +408,26 @@ 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
-            )
+            # Regenerate observations - sync (in transaction) or async (background task)
+            config = get_config()
+            if config.retain_observations_async:
+                # Queue for async processing after transaction commits
+                entity_ids_for_async = list(set(link.entity_id for link in entity_links)) if entity_links else []
+                log_buffer.append(
+                    f"[11] Observations: queued {len(entity_ids_for_async)} entities for async processing"
+                )
+            else:
+                # Run synchronously inside transaction for atomicity
+                await observation_regeneration.regenerate_observations_batch(
+                    conn, embeddings_model, llm_config, bank_id, entity_links, log_buffer
+                )
+                entity_ids_for_async = []

            # 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)
+        # Trigger background tasks AFTER transaction commits
+        await _trigger_background_tasks(task_backend, bank_id, unit_ids, non_duplicate_facts, entity_ids_for_async)

        # Log final summary
        total_time = time.time() - start_time
@@ -404,7 +439,7 @@ async def retain_batch(

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

-        return result_unit_ids
+        return result_unit_ids, usage


 def _map_results_to_contents(
@@ -442,8 +477,9 @@ async def _trigger_background_tasks(
    bank_id: str,
    unit_ids: list[str],
    facts: list[ProcessedFact],
+    entity_ids_for_observations: list[str] | None = None,
 ) -> None:
-    """Trigger opinion reinforcement as background task (after transaction commits)."""
+    """Trigger background tasks 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):
@@ -456,3 +492,13 @@ async def _trigger_background_tasks(
                "unit_entities": fact_entities,
            }
        )
+
+    # Trigger observation regeneration if async mode is enabled
+    if entity_ids_for_observations:
+        await task_backend.submit_task(
+            {
+                "type": "regenerate_observations",
+                "bank_id": bank_id,
+                "entity_ids": entity_ids_for_observations,
+            }
+        )
@@ -20,6 +20,8 @@ class RetainContentDict(TypedDict, total=False):
        event_date: When the content occurred (optional, defaults to now)
        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
@@ -27,6 +29,8 @@ class RetainContentDict(TypedDict, total=False):
    event_date: datetime
    metadata: dict[str, str]
    document_id: str
+    entities: list[dict[str, str]]  # [{"text": "...", "type": "..."}]
+    tags: list[str]  # Visibility scope tags


 def _now_utc() -> datetime:
@@ -46,6 +50,8 @@ class RetainContent:
    context: str = ""
    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
@@ -110,6 +116,7 @@ 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
@@ -152,6 +159,12 @@ class ProcessedFact:
    # DB fields (set after insertion)
    unit_id: UUID | None = None

+    # 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."""
@@ -194,6 +207,8 @@ class ProcessedFact:
            entities=entities,
            causal_relations=extracted_fact.causal_relations,
            chunk_id=chunk_id,
+            content_index=extracted_fact.content_index,
+            tags=extracted_fact.tags,
        )


@@ -225,6 +240,7 @@ 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,7 +11,8 @@ from abc import ABC, abstractmethod

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

 logger = logging.getLogger(__name__)

@@ -42,7 +43,10 @@ class GraphRetriever(ABC):
        query_text: str | None = None,
        semantic_seeds: list[RetrievalResult] | None = None,
        temporal_seeds: list[RetrievalResult] | None = None,
-    ) -> list[RetrievalResult]:
+        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]:
        """
        Retrieve relevant facts via graph traversal.

@@ -55,9 +59,11 @@ 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:
-            List of RetrievalResult objects with activation scores set
+            Tuple of (List of RetrievalResult with activation scores, optional timing info)
        """
        pass

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

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

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

    async def _retrieve_with_conn(
        self,
@@ -135,33 +147,46 @@ 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,
+                   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
            """,
-            query_embedding_str,
-            bank_id,
-            fact_type,
-            self.entry_point_threshold,
-            self.entry_point_limit,
+            *params,
        )

        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 = []
@@ -192,7 +217,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.document_id, mu.chunk_id, mu.tags,
                           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
@@ -232,4 +257,8 @@ 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
@@ -0,0 +1,256 @@
+"""
+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,6 +9,7 @@ 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
@@ -22,7 +23,8 @@ from dataclasses import dataclass, field
 from ..db_utils import acquire_with_retry
 from ..memory_engine import fq_table
 from .graph_retrieval import GraphRetriever
-from .types import RetrievalResult
+from .tags import TagsMatch
+from .types import MPFPTimings, RetrievalResult

 logger = logging.getLogger(__name__)

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


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

-    # edge_type -> from_node_id -> list of (to_node_id, weight)
+    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
    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."""
@@ -63,6 +81,31 @@ class TypedAdjacency:

        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:
@@ -109,66 +152,249 @@ class SeedNode:


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


-def mpfp_traverse(
-    seeds: list[SeedNode],
-    pattern: list[str],
-    adjacency: TypedAdjacency,
-    config: MPFPConfig,
-) -> PatternResult:
+async def load_all_edges_for_frontier(
+    pool,
+    node_ids: list[str],
+    top_k_per_type: int = 20,
+) -> dict[str, dict[str, list[EdgeTarget]]]:
    """
-    Forward Push traversal following a meta-path pattern.
+    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:
-        seeds: Entry point nodes with initial scores
-        pattern: Sequence of edge types to follow
-        adjacency: Typed adjacency structure
-        config: Algorithm parameters
+        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:
-        PatternResult with accumulated scores per node
+        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,
+    seeds: list[SeedNode],
+    pattern: list[str],
+    config: MPFPConfig,
+    cache: EdgeCache,
+) -> PatternResult:
+    """
+    Async Forward Push traversal with lazy edge loading.
+
+    NOTE: For better performance with multiple patterns, use mpfp_traverse_hop_synchronized().
+    This function is kept for single-pattern use cases.
    """
    if not seeds:
        return 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)
+    results = await mpfp_traverse_hop_synchronized(pool, [(seeds, pattern)], config, cache)
+    return results[0] if results else PatternResult(pattern=pattern, scores={})


 def rrf_fusion(
@@ -210,38 +436,6 @@ 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],
@@ -255,7 +449,7 @@ async def fetch_memory_units_by_ids(
        rows = await conn.fetch(
            f"""
            SELECT id, text, context, event_date, occurred_start, occurred_end,
-                   mentioned_at, access_count, embedding, fact_type, document_id, chunk_id
+                   mentioned_at, access_count, embedding, fact_type, document_id, chunk_id, tags
            FROM {fq_table("memory_units")}
            WHERE id = ANY($1::uuid[])
              AND fact_type = $2
@@ -274,10 +468,10 @@ async def fetch_memory_units_by_ids(

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

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

    def __init__(self, config: MPFPConfig | None = None):
@@ -287,8 +481,13 @@ class MPFPGraphRetriever(GraphRetriever):
        Args:
            config: Algorithm configuration (uses defaults if None)
        """
-        self.config = config or MPFPConfig()
-        self._adjacency_cache: dict[str, TypedAdjacency] = {}
+        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

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

        Args:
            pool: Database connection pool
@@ -317,12 +519,15 @@ 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:
-            List of RetrievalResult with activation scores
+            Tuple of (List of RetrievalResult with activation scores, MPFPTimings)
        """
-        # Load typed adjacency (could cache per bank_id with TTL)
-        adjacency = await load_typed_adjacency(pool, bank_id)
+        import time
+
+        timings = MPFPTimings(fact_type=fact_type)

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

        # If no semantic seeds provided, fall back to finding our own
        if not semantic_seed_nodes:
-            semantic_seed_nodes = await self._find_semantic_seeds(pool, query_embedding_str, bank_id, fact_type)
+            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})"
+            )

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

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

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

-        if not tasks:
-            return []
+        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

-        # Gather pattern results
-        pattern_results = await asyncio.gather(*tasks)
+        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

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

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

-        # Get top result IDs (don't exclude seeds - they may be highly relevant)
+        # Get top result IDs
        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}
@@ -387,7 +626,7 @@ class MPFPGraphRetriever(GraphRetriever):
        # Sort by activation
        results.sort(key=lambda r: r.activation or 0, reverse=True)

-        return results
+        return results, timings

    def _convert_seeds(
        self,
@@ -415,8 +654,17 @@ 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"""
@@ -426,14 +674,11 @@ 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
                """,
-                query_embedding_str,
-                bank_id,
-                fact_type,
-                threshold,
-                limit,
+                *params,
            )

        return [SeedNode(node_id=str(r["id"]), score=r["similarity"]) for r in rows]
@@ -44,7 +44,7 @@ class CrossEncoderReranker:
            await cross_encoder.initialize()
        self._initialized = True

-    def rerank(self, query: str, candidates: list[MergedCandidate]) -> list[ScoredResult]:
+    async 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 = self.cross_encoder.predict(pairs)
+        scores = await self.cross_encoder.predict(pairs)

        # Normalize scores using sigmoid to [0, 1] range
        # Cross-encoder returns logits which can be negative
@@ -0,0 +1,172 @@
+"""
+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
@@ -172,7 +172,7 @@ def get_system_message(disposition: DispositionTraits) -> str:
        " ".join(instructions) if instructions else "Balance your disposition traits when interpreting information."
    )

-    return f"You are a person with your own thoughts, experiences, opinions, and disposition. When asked a question, respond naturally like a human would - share what you genuinely think based on what you know and have experienced. {disposition_instruction} Be direct, express your views confidently, and use 'I think', 'I believe', 'in my view', etc. Respond in plain text without markdown formatting."
+    return f"You are a person with your own thoughts, experiences, opinions, and disposition. When asked a question, respond naturally like a human would - share what you genuinely think based on what you know and have experienced. {disposition_instruction} Be direct, express your views confidently, and use 'I think', 'I believe', 'in my view', etc. Respond in plain text without markdown formatting. IMPORTANT: Detect the language of the question and respond in the SAME language. Do not translate to English if the question is in another language."


 async def extract_opinions_from_text(llm_config, text: str, query: str) -> list[Opinion]:
@@ -11,6 +11,13 @@ 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."""

@@ -19,6 +26,11 @@ 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,6 +22,7 @@ from .trace import (
    SearchPhaseMetrics,
    SearchSummary,
    SearchTrace,
+    TemporalConstraint,
    WeightComponents,
 )

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

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

@@ -53,10 +61,14 @@ 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
@@ -66,6 +78,9 @@ 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] = []
@@ -88,6 +103,11 @@ 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.
@@ -428,6 +448,9 @@ 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,6 +10,24 @@ 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:
    """
@@ -30,6 +48,7 @@ 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
@@ -54,6 +73,7 @@ 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"),
@@ -138,6 +158,7 @@ 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,
        }
@@ -121,6 +121,29 @@ class SyncTaskBackend(TaskBackend):
        logger.debug("SyncTaskBackend shutdown")


+class NoopTaskBackend(TaskBackend):
+    """
+    No-op task backend that discards all tasks.
+
+    This is useful for tests where background task execution is not needed
+    and would only slow down the test suite.
+    """
+
+    async def initialize(self):
+        """No-op."""
+        self._initialized = True
+        logger.debug("NoopTaskBackend initialized")
+
+    async def submit_task(self, task_dict: dict[str, Any]):
+        """Discard the task (do nothing)."""
+        pass
+
+    async def shutdown(self):
+        """No-op."""
+        self._initialized = False
+        logger.debug("NoopTaskBackend shutdown")
+
+
 class AsyncIOQueueBackend(TaskBackend):
    """
    Task backend implementation using asyncio queues.
@@ -129,7 +152,7 @@ class AsyncIOQueueBackend(TaskBackend):
    and a periodic consumer worker.
    """

-    def __init__(self, batch_size: int = 100, batch_interval: float = 1.0):
+    def __init__(self, batch_size: int = 10, batch_interval: float = 1.0):
        """
        Initialize AsyncIO queue backend.

@@ -143,6 +166,8 @@ class AsyncIOQueueBackend(TaskBackend):
        self._shutdown_event: asyncio.Event | None = None
        self._batch_size = batch_size
        self._batch_interval = batch_interval
+        self._in_flight_count = 0
+        self._in_flight_lock = asyncio.Lock()

    async def initialize(self):
        """Initialize the queue and start the worker."""
@@ -166,33 +191,31 @@ class AsyncIOQueueBackend(TaskBackend):
            await self.initialize()

        await self._queue.put(task_dict)
-        task_type = task_dict.get("type", "unknown")
-        task_id = task_dict.get("id")

-    async def wait_for_pending_tasks(self, timeout: float = 5.0):
+    async def wait_for_pending_tasks(self, timeout: float = 120.0):
        """
-        Wait for all pending tasks in the queue to be processed.
+        Wait for all pending tasks in the queue and in-flight tasks to complete.

        This is useful in tests to ensure background tasks complete before assertions.

        Args:
-            timeout: Maximum time to wait in seconds
+            timeout: Maximum time to wait in seconds (default 120s for long-running tasks)
        """
        if not self._initialized or self._queue is None:
            return

-        # Wait for queue to be empty and give worker time to process
+        # Wait for queue to be empty AND no in-flight tasks
        start_time = asyncio.get_event_loop().time()
        while asyncio.get_event_loop().time() - start_time < timeout:
-            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)
+            async with self._in_flight_lock:
+                in_flight = self._in_flight_count
+
+            if self._queue.empty() and in_flight == 0:
+                # Queue is empty and no tasks in flight, we're done
+                return
+
+            # Wait a bit before checking again
+            await asyncio.sleep(0.5)

    async def shutdown(self):
        """Shutdown the worker and drain the queue."""
@@ -215,6 +238,39 @@ class AsyncIOQueueBackend(TaskBackend):
        self._initialized = False
        logger.info("AsyncIOQueueBackend shutdown complete")

+    async def _execute_task_with_tracking(self, task_dict: dict[str, Any]):
+        """Execute a task and track its in-flight status."""
+        async with self._in_flight_lock:
+            self._in_flight_count += 1
+        try:
+            await self._execute_task(task_dict)
+        finally:
+            async with self._in_flight_lock:
+                self._in_flight_count -= 1
+
+    async def _execute_task_no_tracking(self, task_dict: dict[str, Any]):
+        """Execute a task without in-flight tracking (tracking done at batch level)."""
+        await self._execute_task(task_dict)
+
+    def _get_queue_stats(self) -> tuple[int, dict[str, int]]:
+        """Get current queue size and bank_id distribution."""
+        queue_size = self._queue.qsize() if self._queue else 0
+        bank_distribution: dict[str, int] = {}
+
+        if queue_size > 0 and self._queue:
+            # Peek at queue items without removing them
+            # Note: This is a snapshot and may not be perfectly accurate due to concurrency
+            try:
+                # Access internal deque for logging purposes only
+                items = list(self._queue._queue)  # type: ignore[attr-defined]
+                for item in items:
+                    bank_id = item.get("bank_id", "unknown")
+                    bank_distribution[bank_id] = bank_distribution.get(bank_id, 0) + 1
+            except Exception:
+                pass  # Queue access failed, return empty distribution
+
+        return queue_size, bank_distribution
+
    async def _worker(self):
        """
        Background worker that processes tasks in batches.
@@ -232,17 +288,52 @@ class AsyncIOQueueBackend(TaskBackend):
                    try:
                        remaining_time = max(0.1, deadline - asyncio.get_event_loop().time())
                        task_dict = await asyncio.wait_for(self._queue.get(), timeout=remaining_time)
+                        # Track task as in-flight immediately when picked up from queue
+                        # This prevents wait_for_pending_tasks from returning too early
+                        async with self._in_flight_lock:
+                            self._in_flight_count += 1
                        tasks.append(task_dict)
                    except TimeoutError:
                        break

                # Process batch
                if tasks:
-                    # Execute tasks concurrently
+                    # Log batch start with queue stats
+                    queue_size, bank_distribution = self._get_queue_stats()
+
+                    # Summarize batch by task type and bank
+                    batch_summary: dict[str, dict[str, int]] = {}
+                    for task_dict in tasks:
+                        task_type = task_dict.get("type", "unknown")
+                        bank_id = task_dict.get("bank_id", "unknown")
+                        if task_type not in batch_summary:
+                            batch_summary[task_type] = {}
+                        batch_summary[task_type][bank_id] = batch_summary[task_type].get(bank_id, 0) + 1
+
+                    # Build log message
+                    batch_parts = []
+                    for task_type, banks in sorted(batch_summary.items()):
+                        bank_str = ", ".join(f"{b}:{c}" for b, c in sorted(banks.items()))
+                        batch_parts.append(f"{task_type}[{bank_str}]")
+                    batch_str = ", ".join(batch_parts)
+
+                    if queue_size > 0:
+                        pending_str = ", ".join(f"{k}:{v}" for k, v in sorted(bank_distribution.items()))
+                        logger.info(
+                            f"Processing {len(tasks)} tasks: {batch_str} (pending={queue_size} [{pending_str}])"
+                        )
+                    else:
+                        logger.info(f"Processing {len(tasks)} tasks: {batch_str}")
+
+                    # Execute tasks concurrently (in_flight already tracked when picked up)
                    await asyncio.gather(
-                        *[self._execute_task(task_dict) for task_dict in tasks], return_exceptions=True
+                        *[self._execute_task_no_tracking(task_dict) for task_dict in tasks], return_exceptions=True
                    )

+                    # Decrement in_flight count after all tasks complete
+                    async with self._in_flight_lock:
+                        self._in_flight_count -= len(tasks)
+
            except asyncio.CancelledError:
                break
            except Exception as e:
@@ -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,
@@ -96,9 +96,25 @@ class DefaultExtensionContext(ExtensionContext):

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

-        run_migrations(self._database_url, schema=schema)
+        # Prefer getting URL from memory engine (handles pg0 case where URL is set after init)
+        db_url = self._database_url
+        if self._memory_engine is not None:
+            engine_url = getattr(self._memory_engine, "db_url", None)
+            if engine_url:
+                db_url = engine_url
+
+        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."""
@@ -17,8 +17,9 @@ if TYPE_CHECKING:
 class OperationValidationError(Exception):
    """Raised when an operation fails validation."""

-    def __init__(self, reason: str):
+    def __init__(self, reason: str, status_code: int = 403):
        self.reason = reason
+        self.status_code = status_code
        super().__init__(f"Operation validation failed: {reason}")


@@ -28,6 +29,7 @@ class ValidationResult:

    allowed: bool
    reason: str | None = None
+    status_code: int = 403  # Default to Forbidden

    @classmethod
    def accept(cls) -> "ValidationResult":
@@ -35,9 +37,9 @@ class ValidationResult:
        return cls(allowed=True)

    @classmethod
-    def reject(cls, reason: str) -> "ValidationResult":
-        """Create a rejected validation result with a reason."""
-        return cls(allowed=False, reason=reason)
+    def reject(cls, reason: str, status_code: int = 403) -> "ValidationResult":
+        """Create a rejected validation result with a reason and HTTP status code."""
+        return cls(allowed=False, reason=reason, status_code=status_code)


 # =============================================================================
@@ -23,7 +23,7 @@ import uvicorn
 from . import MemoryEngine
 from .api import create_app
 from .banner import print_banner
-from .config import HindsightConfig, get_config
+from .config import DEFAULT_WORKERS, ENV_WORKERS, HindsightConfig, get_config
 from .daemon import (
    DEFAULT_DAEMON_PORT,
    DEFAULT_IDLE_TIMEOUT,
@@ -31,6 +31,7 @@ from .daemon import (
    IdleTimeoutMiddleware,
    daemonize,
 )
+from .extensions import DefaultExtensionContext, OperationValidatorExtension, TenantExtension, load_extension

 # Filter deprecation warnings from third-party libraries
 warnings.filterwarnings("ignore", message="websockets.legacy is deprecated")
@@ -94,7 +95,12 @@ 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=1, help="Number of worker processes (default: 1)")
+    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})",
+    )

    # Access log options
    parser.add_argument("--access-log", action="store_true", help="Enable access log")
@@ -168,19 +174,50 @@ def main():
            llm_api_key=config.llm_api_key,
            llm_model=config.llm_model,
            llm_base_url=config.llm_base_url,
+            llm_max_concurrent=config.llm_max_concurrent,
+            llm_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,
            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,
            host=args.host,
            port=args.port,
            log_level=args.log_level,
            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,
+            task_backend=config.task_backend,
+            task_backend_memory_batch_size=config.task_backend_memory_batch_size,
+            task_backend_memory_batch_interval=config.task_backend_memory_batch_interval,
        )
    config.configure_logging()
    if not args.daemon:
@@ -191,8 +228,35 @@ def main():
    signal.signal(signal.SIGINT, _signal_handler)
    signal.signal(signal.SIGTERM, _signal_handler)

+    # Load operation validator extension if configured
+    operation_validator = load_extension("OPERATION_VALIDATOR", OperationValidatorExtension)
+    if operation_validator:
+        import logging
+
+        logging.info(f"Loaded operation validator: {operation_validator.__class__.__name__}")
+
+    # Load tenant extension if configured
+    tenant_extension = load_extension("TENANT", TenantExtension)
+    if tenant_extension:
+        import logging
+
+        logging.info(f"Loaded tenant extension: {tenant_extension.__class__.__name__}")
+
    # Create MemoryEngine (reads configuration from environment)
-    _memory = MemoryEngine()
+    _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")

    # Create FastAPI app
    app = create_app(
@@ -210,14 +274,27 @@ 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": app,
+        "app": "hindsight_api.server:app" if use_import_string else 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,17 +5,77 @@ 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
+
+# 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
@@ -48,8 +108,30 @@ def initialize_metrics(service_name: str = "hindsight-api", service_version: str
    # Create Prometheus metric reader
    prometheus_reader = PrometheusMetricReader()

-    # Create meter provider with Prometheus exporter
-    provider = MeterProvider(resource=resource, metric_readers=[prometheus_reader])
+    # 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],
+    )

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

    @contextmanager
-    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_tokens(
+    def record_operation(
        self,
        operation: str,
        bank_id: str,
-        input_tokens: int = 0,
-        output_tokens: int = 0,
+        source: str = "api",
        budget: str | None = None,
        max_tokens: int | None = None,
    ):
-        """Record token usage for an operation."""
+        """Context manager to record operation duration and status."""
        raise NotImplementedError

+    def record_llm_call(
+        self,
+        provider: str,
+        model: str,
+        scope: str,
+        duration: float,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        success: bool = True,
+    ):
+        """
+        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
+        """
+        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, budget: str | None = None, max_tokens: int | None = None):
-        """No-op context manager."""
-        yield
-
-    def record_tokens(
+    def record_operation(
        self,
        operation: str,
        bank_id: str,
-        input_tokens: int = 0,
-        output_tokens: int = 0,
+        source: str = "api",
        budget: str | None = None,
        max_tokens: int | None = None,
    ):
-        """No-op token recording."""
+        """No-op context manager."""
+        yield
+
+    def record_llm_call(
+        self,
+        provider: str,
+        model: str,
+        scope: str,
+        duration: float,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        success: bool = True,
+    ):
+        """No-op LLM call 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):
    """
@@ -125,33 +248,73 @@ 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, budget: str | None = None, max_tokens: int | None = None):
+    def record_operation(
+        self,
+        operation: str,
+        bank_id: str,
+        source: str = "api",
+        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", budget="mid", max_tokens=4096):
+            with metrics.record_operation("recall", bank_id="user123", source="api", budget="mid", max_tokens=4096):
                # ... perform operation
                pass

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

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

        Args:
-            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
+            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
        """
-        attributes = {
-            "operation": operation,
-            "bank_id": bank_id,
+        # Base attributes for all metrics
+        base_attributes = {
+            "provider": provider,
+            "model": model,
+            "scope": scope,
+            "success": str(success).lower(),
        }
-        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:
-            self.tokens_input.add(input_tokens, attributes)
+            input_attributes = {
+                **base_attributes,
+                "token_bucket": get_token_bucket(input_tokens),
+            }
+            self.llm_tokens_input.add(input_tokens, input_attributes)

        if output_tokens > 0:
-            self.tokens_output.add(output_tokens, attributes)
+            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"
+
+            attributes = {
+                **base_attributes,
+                "status_code": str(status_code),
+                "status_class": status_class,
+            }
+
+            # 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}",
+        )


 # Global metrics collector instance (defaults to no-op)
@@ -22,6 +22,7 @@ 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__)
@@ -78,7 +79,18 @@ def _run_migrations_internal(database_url: str, script_location: str, schema: st
        alembic_cfg.set_main_option("target_schema", schema)

    # Run migrations
-    command.upgrade(alembic_cfg, "head")
+    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

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

@@ -229,3 +241,131 @@ 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}")
@@ -18,6 +18,9 @@ class RequestContext:
    """

    api_key: str | None = None
+    api_key_id: str | None = None  # UUID of the API key used for authentication
+    tenant_id: str | None = None  # Tenant identifier (set by extension after auth)
+    internal: bool = False  # True for background/internal operations (not user-visible)


 from pgvector.sqlalchemy import Vector
@@ -38,6 +41,8 @@ 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."""
@@ -78,7 +83,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(384))  # pgvector type
+    embedding = mapped_column(Vector(EMBEDDING_DIMENSION))  # pgvector type
    context: Mapped[str | None] = mapped_column(Text)
    event_date: Mapped[datetime] = mapped_column(
        TIMESTAMP(timezone=True), nullable=False
@@ -132,3 +132,56 @@ 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
@@ -27,10 +27,17 @@ config.configure_logging()

 # Create app at module level (required for uvicorn import string)
 # MemoryEngine reads configuration from environment variables automatically
-_memory = MemoryEngine()
+# Note: run_migrations=True by default, but migrations are idempotent so safe with workers
+_memory = MemoryEngine(run_migrations=config.run_migrations_on_startup)

 # 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")
+app = create_app(
+    memory=_memory,
+    http_api_enabled=True,
+    mcp_api_enabled=config.mcp_enabled,
+    mcp_mount_path="/mcp",
+    initialize_memory=True,
+)


 if __name__ == "__main__":
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-api"
-version = "0.1.14"
+version = "0.2.1"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,7 +14,6 @@ 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",
@@ -24,8 +23,6 @@ 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.3.0",
@@ -37,6 +34,15 @@ dependencies = [
    "opentelemetry-exporter-prometheus>=0.41b0",
    "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.0.0,<3.3.0",
+    "transformers>=4.30.0,<4.46.0",
+    "torch>=2.0.0",
+    "uvloop>=0.22.1",
 ]

 [project.optional-dependencies]
@@ -51,6 +57,7 @@ test = [
 [project.scripts]
 hindsight-api = "hindsight_api.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"]
@@ -74,7 +81,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 --durations=10 -v"
+addopts = "--timeout 120 -n 8 --dist loadgroup --durations=10 -v"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 log_auto_indent = true
@@ -119,6 +126,9 @@ 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"
@@ -0,0 +1,292 @@
+"""
+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()
@@ -0,0 +1,223 @@
+"""
+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}"
+                    )
@@ -0,0 +1,202 @@
+"""
+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]}..."
+                    )
@@ -0,0 +1,603 @@
+"""
+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.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),
+        )
+
+        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),
+        )
+
+        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),
+        )
+
+        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
@@ -0,0 +1,103 @@
+"""
+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"
@@ -0,0 +1,288 @@
+"""
+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,6 +354,7 @@ 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.
@@ -366,7 +367,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,
@@ -379,20 +380,18 @@ 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", "soon", "lately", "a while ago", "some time ago"]
+        prohibited_terms = ["recently", "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}"
        )

-        # 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"
+        # 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]}"
        )

    @pytest.mark.asyncio
@@ -402,6 +401,8 @@ I'm planning to visit Tokyo next month.

        Ideally: If conversation is on August 14, 2023 and text says "last night",
        the date field should be August 13. We accept 13 or 14 as LLM may vary.
+
+        Retries up to 3 times to account for LLM inconsistencies.
        """
        text = """
 Melanie: Hey Caroline! Last night was amazing! We celebrated my daughter's birthday
@@ -410,47 +411,76 @@ with a concert surrounded by music, joy and the warm summer breeze.

        context = "Conversation between Melanie and Caroline"
        llm_config = LLMConfig.for_memory()
-
        event_date = datetime(2023, 8, 14, 14, 24)

-        facts, _ = await extract_facts_from_text(
-            text=text,
-            event_date=event_date,
-            context=context,
-            llm_config=llm_config,
-            agent_name="Melanie"
-        )
+        last_error = None
+        max_retries = 3

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

-        birthday_fact = None
-        for fact in facts:
-            if "birthday" in fact.fact.lower() or "concert" in fact.fact.lower():
-                birthday_fact = fact
-                break
+                assert len(facts) > 0, "Should extract at least one fact"

-        assert birthday_fact is not None, "Should extract fact about birthday celebration"
+                birthday_fact = None
+                for fact in facts:
+                    if "birthday" in fact.fact.lower() or "concert" in fact.fact.lower():
+                        birthday_fact = fact
+                        break

-        fact_date_str = birthday_fact.occurred_start
-        assert fact_date_str is not None, "occurred_start should not be None for temporal events"
+                assert birthday_fact is not None, "Should extract fact about birthday celebration"

-        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 = birthday_fact.occurred_start
+                assert fact_date_str is not None, "occurred_start should not be None for temporal events"

-        assert fact_date.year == 2023, "Year should be 2023"
-        assert fact_date.month == 8, "Month should be August"
-        # Accept day 13 (ideal: last night) or 14 (conversation date) as valid
-        assert fact_date.day in (13, 14), (
-            f"Day should be 13 or 14 (around Aug 14 event), but got {fact_date.day}."
-        )
+                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 == 2023, "Year should be 2023"
+                assert fact_date.month == 8, "Month should be August"
+                # Accept day 13 (ideal: last night) or 14 (conversation date) as valid
+                assert fact_date.day in (13, 14), (
+                    f"Day should be 13 or 14 (around Aug 14 event), but got {fact_date.day}."
+                )
+
+                # If we reach here, test passed
+                return
+
+            except AssertionError as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    print(f"Test attempt {attempt + 1} failed: {e}. Retrying...")
+                    continue
+                else:
+                    # Last attempt failed, re-raise the error
+                    raise e
+            except Exception as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    print(f"Test attempt {attempt + 1} failed with exception: {e}. Retrying...")
+                    continue
+                else:
+                    # Last attempt failed, re-raise the error
+                    raise e
+
+        # Should not reach here, but just in case
+        if last_error:
+            raise last_error

    @pytest.mark.asyncio
    async def test_date_field_calculation_yesterday(self):
        """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"
@@ -458,7 +488,7 @@ Yesterday I went for a morning jog for the first time in a nearby park.

        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,
@@ -468,25 +498,30 @@ Yesterday I went for a morning jog for the first time in a nearby park.

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

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

-        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)
+        # 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)

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

-        assert "first time" in all_facts_text or "first" in all_facts_text, \
-            "Should preserve 'first time' qualifier"
+        # 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 "recently" not in all_facts_text, \
            "Should NOT convert 'yesterday' to 'recently'"
@@ -507,7 +542,7 @@ Yesterday I went for a morning jog for the first time in a nearby park.
        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,
@@ -537,7 +572,7 @@ Yesterday I went for a morning jog for the first time in a nearby park.

        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,
@@ -564,7 +599,7 @@ Yesterday I went for a morning jog for the first time in a nearby park.
        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,
@@ -615,7 +650,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,
@@ -665,7 +700,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,
@@ -683,15 +718,21 @@ I've learned so much from it.
        assert has_project, "Should mention the project"
        assert has_qualities, "Should mention the qualities/learning"

-        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
+        # 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()]

-        assert connected_fact_found, (
-            "Should resolve 'it' to 'the project' and connect characteristics in the same fact. "
+        # 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. "
            f"Facts: {[f.fact for f in facts]}"
        )

@@ -728,7 +769,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,
@@ -773,7 +814,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,
@@ -808,7 +849,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,
@@ -842,6 +883,8 @@ 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 = """
@@ -867,26 +910,41 @@ so the algorithm learns to box out. See you next week!

        llm_config = LLMConfig.for_memory()

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

-        assert len(facts) > 0, "Should extract at least one fact"
+        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
+                )

-        # 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])
+                assert len(facts) > 0, "Should extract at least one fact"

-        # 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]}"
+                # 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


 # =============================================================================
@@ -250,11 +250,34 @@ async def test_full_api_workflow(api_client, test_bank_id):
    # 8. Test Entity Endpoints
    # ================================================================

-    # List entities
+    # List entities with pagination
    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:
@@ -288,8 +311,9 @@ async def test_full_api_workflow(api_client, test_bank_id):
    # 10. Clean Up
    # ================================================================

-    # Note: No delete bank endpoint in API, so test data remains in DB
-    # Using timestamped bank IDs prevents conflicts between test runs
+    # 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


@pytest.mark.asyncio
@@ -428,6 +452,147 @@ async def test_document_deletion(api_client):
    assert response.status_code == 404


+@pytest.mark.asyncio
+async def test_document_deletion_with_slashes_in_id(api_client):
+    """
+    Test document deletion when document_id contains forward slashes.
+
+    Regression test for https://github.com/vectorize-io/hindsight/issues/92
+
+    Document IDs with slashes (e.g., "folder/file.md") should work correctly
+    for all operations including creation, listing, retrieval, and deletion.
+    """
+    import urllib.parse
+
+    test_bank_id = f"doc_slash_test_{datetime.now().timestamp()}"
+    document_id_with_slash = "reports/quarterly/q1-2024.md"
+
+    try:
+        # 1. Create a document with slashes in its ID
+        response = await api_client.post(
+            f"/v1/default/banks/{test_bank_id}/memories",
+            json={
+                "items": [
+                    {
+                        "content": "The Q1 2024 report shows significant growth in user engagement.",
+                        "context": "quarterly report",
+                        "document_id": document_id_with_slash
+                    }
+                ]
+            }
+        )
+        assert response.status_code == 200, f"Failed to create document: {response.text}"
+
+        # 2. Verify document exists via list endpoint
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/documents")
+        assert response.status_code == 200
+        documents = response.json()
+        doc_ids = [doc["id"] for doc in documents["items"]]
+        assert document_id_with_slash in doc_ids, f"Document should be in list: {doc_ids}"
+
+        # 3. Delete the document (slashes in document_id should work with :path converter)
+        encoded_doc_id = urllib.parse.quote(document_id_with_slash, safe="")
+        response = await api_client.delete(
+            f"/v1/default/banks/{test_bank_id}/documents/{encoded_doc_id}"
+        )
+        assert response.status_code == 200, (
+            f"Failed to delete document with slashes in ID. "
+            f"Status: {response.status_code}, Response: {response.text}"
+        )
+
+        # Verify document is deleted
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/documents")
+        assert response.status_code == 200
+        documents = response.json()
+        doc_ids = [doc["id"] for doc in documents["items"]]
+        assert document_id_with_slash not in doc_ids, "Document should be deleted"
+
+    finally:
+        # Cleanup - delete the bank
+        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.
@@ -521,11 +686,14 @@ 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
+    # 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"]
    documents = [
        {
-            "content": f"Document {i}: This is test content about Person{i} who works at Company{i}.",
-            "context": f"test document {i}",
+            "content": f"{people[i]} is a software engineer who works at {companies[i]} and specializes in Python development.",
+            "context": f"employee profile {i}",
            "document_id": f"doc_{i}"
        }
        for i in range(num_documents)
@@ -608,3 +776,298 @@ async def test_async_retain_parallel(api_client):
        assert response.status_code == 200
        results = response.json()["results"]
        assert len(results) > 0, f"Should find memories for document {i}"
+
+
+@pytest.mark.asyncio
+async def test_reflect_structured_output(api_client):
+    """Test reflect endpoint with structured output via response_schema.
+
+    When response_schema is provided, the reflect endpoint should return
+    both the natural language text response and a structured_output field
+    containing the response parsed according to the provided JSON schema.
+    """
+    test_bank_id = f"reflect_structured_test_{datetime.now().timestamp()}"
+
+    # Store some memories to reflect on
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {
+                    "content": "Alice is a senior machine learning engineer with 8 years of experience.",
+                    "context": "team member info"
+                },
+                {
+                    "content": "Bob is a junior data scientist who joined last month.",
+                    "context": "team member info"
+                },
+                {
+                    "content": "The team uses Python and TensorFlow for most projects.",
+                    "context": "tech stack"
+                }
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Define a JSON schema for structured output
+    response_schema = {
+        "type": "object",
+        "properties": {
+            "team_members": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "role": {"type": "string"},
+                        "experience_level": {"type": "string"}
+                    }
+                }
+            },
+            "technologies": {
+                "type": "array",
+                "items": {"type": "string"}
+            },
+            "summary": {"type": "string"}
+        },
+        "required": ["team_members", "summary"]
+    }
+
+    # Call reflect with response_schema
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/reflect",
+        json={
+            "query": "Give me an overview of the team and their tech stack",
+            "response_schema": response_schema
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+
+    # 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
+    assert result["structured_output"] is not None
+
+    structured = result["structured_output"]
+    assert "team_members" in structured
+    assert "summary" in structured
+    assert isinstance(structured["team_members"], list)
+    assert isinstance(structured["summary"], str)
+
+    # Verify team members have the expected fields
+    if len(structured["team_members"]) > 0:
+        member = structured["team_members"][0]
+        assert "name" in member or "role" in member  # At least some fields should be present
+
+
+@pytest.mark.asyncio
+async def test_reflect_without_structured_output(api_client):
+    """Test that reflect works normally without response_schema.
+
+    When response_schema is not provided, the structured_output field
+    should be null/None in the response.
+    """
+    test_bank_id = f"reflect_no_structured_test_{datetime.now().timestamp()}"
+
+    # Store a memory
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {
+                    "content": "The project deadline is next Friday.",
+                    "context": "project timeline"
+                }
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Call reflect without response_schema
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/reflect",
+        json={
+            "query": "When is the project deadline?"
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+
+    # Verify response has text but structured_output is null
+    assert "text" in result
+    assert len(result["text"]) > 0
+    assert result.get("structured_output") is None
+
+
+@pytest.mark.asyncio
+async def test_reflect_with_max_tokens(api_client):
+    """Test reflect endpoint with custom max_tokens parameter.
+
+    The max_tokens parameter controls the maximum tokens for the LLM response.
+    """
+    test_bank_id = f"reflect_max_tokens_test_{datetime.now().timestamp()}"
+
+    # Store a memory
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {
+                    "content": "Python is a popular programming language for data science and machine learning.",
+                    "context": "tech"
+                }
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Call reflect with custom max_tokens
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/reflect",
+        json={
+            "query": "What is Python used for?",
+            "max_tokens": 500
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+
+    # 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 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 reflect"
+    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']}")
+
+
+@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"
@@ -0,0 +1,245 @@
+"""
+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}")
@@ -0,0 +1,316 @@
+"""
+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.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
+        )
+        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
@@ -1,177 +0,0 @@
-"""
-Integration test for the MCP (Model Context Protocol) server.
-
-Tests MCP endpoints by starting a FastAPI server with MCP enabled and using the MCP client.
-
-Note: MCP server is integrated with the web server. These tests require HINDSIGHT_API_MCP_ENABLED=true.
-"""
-import asyncio
-import pytest
-import pytest_asyncio
-import httpx
-from mcp import ClientSession
-from mcp.client.sse import sse_client
-from hindsight_api.api import create_app
-
-
-@pytest_asyncio.fixture
-async def mcp_server(memory):
-    """Start the FastAPI app with MCP enabled and return the SSE URL."""
-    # Memory is already initialized by the conftest fixture (with migrations)
-    app = create_app(
-        memory,
-        initialize_memory=False,
-        mcp_api_enabled=True
-    )
-
-    # Use httpx to create a test server
-    transport = httpx.ASGITransport(app=app)
-    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
-        # The MCP SSE endpoint is at /mcp/sse
-        # We need to yield the base URL for sse_client to connect
-        # However, sse_client expects a real URL, not a test client
-        # So we'll start a real server on a random port
-        pass
-
-    # For now, skip these tests as they require a real server
-    # The sse_client doesn't work with ASGI test transport
-    pytest.skip("MCP tests require a real running server. Run: HINDSIGHT_API_MCP_ENABLED=true uvicorn hindsight_api.api:app")
-
-
-@pytest.mark.asyncio
-async def test_mcp_server_tools_via_sse(mcp_server):
-    """Test MCP server tools via SSE transport using proper MCP client."""
-    sse_url = mcp_server
-
-    async with sse_client(sse_url) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-
-            # Test 1: List tools
-            tools_list = await session.list_tools()
-            print(f"Tools: {tools_list}")
-            tool_names = [t.name for t in tools_list.tools]
-            assert "hindsight_search" in tool_names
-            assert "hindsight_put" in tool_names
-
-            # Test 2: Call hindsight_put
-            put_result = await session.call_tool(
-                "hindsight_put",
-                arguments={
-                    "content": "User loves Python programming",
-                    "context": "programming_preferences",
-                    "explanation": "Storing user's programming language preference"
-                }
-            )
-            print(f"Put result: {put_result}")
-            assert put_result is not None
-
-            # Wait a bit for indexing
-            await asyncio.sleep(1)
-
-            # Test 3: Call hindsight_search
-            search_result = await session.call_tool(
-                "hindsight_search",
-                arguments={
-                    "query": "What programming languages does the user like?",
-                    "max_tokens": 4096,
-                    "explanation": "Searching for programming preferences"
-                }
-            )
-            print(f"Search result: {search_result}")
-            assert search_result is not None
-
-
-@pytest.mark.asyncio
-async def test_multiple_concurrent_requests(mcp_server):
-    """Test multiple concurrent requests from a single session."""
-    sse_url = mcp_server
-
-    async with sse_client(sse_url) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-
-            # Fire off 10 concurrent search requests from same session
-            async def make_search(idx):
-                try:
-                    result = await session.call_tool(
-                        "hindsight_search",
-                        arguments={
-                            "query": f"test query {idx}",
-                            "explanation": f"Concurrent test {idx}"
-                        }
-                    )
-                    return idx, "success", result
-                except Exception as e:
-                    return idx, "error", str(e)
-
-            tasks = [make_search(i) for i in range(10)]
-            results = await asyncio.gather(*tasks, return_exceptions=True)
-
-            # Check results
-            successes = 0
-            failures = 0
-
-            for result in results:
-                if isinstance(result, Exception):
-                    print(f"Request failed with exception: {result}")
-                    failures += 1
-                else:
-                    idx, status, data = result
-                    if status == "success":
-                        successes += 1
-                    else:
-                        print(f"Request {idx} failed: {data}")
-                        failures += 1
-
-            print(f"Successes: {successes}, Failures: {failures}")
-
-            # We expect all requests to succeed
-            assert successes >= 8, f"Too many failures: {failures}/10"
-
-
-@pytest.mark.asyncio
-async def test_race_condition_with_rapid_requests(mcp_server):
-    """Test rapid-fire requests with multiple sessions to trigger race condition."""
-    sse_url = mcp_server
-
-    async def rapid_session_search(idx):
-        """Create a new session and immediately make a request."""
-        try:
-            async with sse_client(sse_url) as (read, write):
-                async with ClientSession(read, write) as session:
-                    await session.initialize()
-
-                    # Make request immediately after initialization
-                    result = await session.call_tool(
-                        "hindsight_search",
-                        arguments={
-                            "query": f"rapid query {idx}",
-                            "max_tokens": 2048
-                        }
-                    )
-                    return idx, "success", result
-        except Exception as e:
-            return idx, "error", str(e)
-
-    # Fire 20 requests with minimal delay, each with its own session
-    tasks = [rapid_session_search(i) for i in range(20)]
-    results = await asyncio.gather(*tasks)
-
-    # Analyze results
-    errors = []
-    for idx, status, data in results:
-        if status == "error":
-            errors.append((idx, data))
-
-    if errors:
-        print(f"Found {len(errors)} errors:")
-        for idx, error_msg in errors:
-            print(f"  Request {idx}: {error_msg}")
-
-    # Most requests should succeed
-    assert len(errors) < 5, f"Too many errors: {len(errors)}/20"
-
-
-if __name__ == "__main__":
-    pytest.main([__file__, "-v", "-s"])
@@ -9,6 +9,7 @@ def mock_memory():
    """Create a mock MemoryEngine."""
    memory = MagicMock()
    memory.retain_batch_async = AsyncMock()
+    memory.submit_async_retain = AsyncMock(return_value={"operation_id": "test-op-123"})
    memory.recall_async = AsyncMock(return_value=MagicMock(results=[]))
    return memory

@@ -44,11 +45,11 @@ async def test_mcp_tools_use_context_bank_id(mock_memory):
    assert "retain" in tools
    assert "recall" in tools

-    # Test retain with bank_id from context
+    # Test retain with bank_id from context (use async_processing=False for synchronous test)
    token = _current_bank_id.set("context-bank-id")
    try:
        retain_tool = tools["retain"]
-        result = await retain_tool.fn(content="test content", context="test_context")
+        result = await retain_tool.fn(content="test content", context="test_context", async_processing=False)
        assert "successfully" in result.lower()

        # Verify the memory was called with the context bank_id
@@ -0,0 +1,391 @@
+"""Tests for metrics instrumentation."""
+import pytest
+from unittest.mock import MagicMock, patch
+
+from hindsight_api.metrics import (
+    MetricsCollector,
+    MetricsCollectorBase,
+    NoOpMetricsCollector,
+    get_metrics_collector,
+    get_token_bucket,
+    create_metrics_collector,
+    initialize_metrics,
+)
+
+
+class TestNoOpMetricsCollector:
+    """Tests for the no-op metrics collector."""
+
+    def test_record_operation_is_noop(self):
+        """Test that record_operation does nothing."""
+        collector = NoOpMetricsCollector()
+
+        # Should not raise any exception
+        with collector.record_operation("recall", bank_id="test_bank", source="api"):
+            pass
+
+    def test_nested_contexts_work(self):
+        """Test that nested context managers work correctly."""
+        collector = NoOpMetricsCollector()
+
+        # Nested contexts should work without issues
+        with collector.record_operation("reflect", bank_id="test_bank", source="api"):
+            with collector.record_operation("recall", bank_id="test_bank", source="reflect"):
+                pass
+
+    def test_exception_propagates(self):
+        """Test that exceptions inside context are propagated."""
+        collector = NoOpMetricsCollector()
+
+        with pytest.raises(ValueError, match="test error"):
+            with collector.record_operation("recall", bank_id="test_bank"):
+                raise ValueError("test error")
+
+    def test_record_llm_call_is_noop(self):
+        """Test that record_llm_call does nothing."""
+        collector = NoOpMetricsCollector()
+
+        # Should not raise any exception
+        collector.record_llm_call(
+            provider="openai",
+            model="gpt-4",
+            scope="memory",
+            duration=1.5,
+            input_tokens=100,
+            output_tokens=50,
+            success=True,
+        )
+
+
+class TestMetricsCollector:
+    """Tests for the real metrics collector."""
+
+    @pytest.fixture
+    def mock_meter(self):
+        """Create a mock meter for testing."""
+        meter = MagicMock()
+        # Create separate mocks for each histogram (operation_duration, llm_duration, http_request_duration)
+        histogram_mocks = [MagicMock(), MagicMock(), MagicMock()]
+        meter.create_histogram.side_effect = histogram_mocks
+        # Create separate mocks for each counter
+        # (operation_total, llm_tokens_input, llm_tokens_output, llm_calls_total, http_requests_total)
+        counter_mocks = [MagicMock() for _ in range(5)]
+        meter.create_counter.side_effect = counter_mocks
+        return meter
+
+    @pytest.fixture
+    def collector(self, mock_meter):
+        """Create a MetricsCollector with a mock meter."""
+        with patch("hindsight_api.metrics.get_meter", return_value=mock_meter):
+            return MetricsCollector()
+
+    def test_record_operation_records_duration(self, collector):
+        """Test that record_operation records duration."""
+        with collector.record_operation("recall", bank_id="test_bank", source="api"):
+            pass
+
+        # Histogram should have been called
+        collector.operation_duration.record.assert_called_once()
+        call_args = collector.operation_duration.record.call_args
+
+        # First arg is duration (should be > 0)
+        duration = call_args[0][0]
+        assert duration >= 0
+
+        # Second arg is attributes dict
+        attributes = call_args[0][1]
+        assert attributes["operation"] == "recall"
+        assert attributes["bank_id"] == "test_bank"
+        assert attributes["source"] == "api"
+        assert attributes["success"] == "true"
+
+    def test_record_operation_records_failure_on_exception(self, collector):
+        """Test that record_operation records failure when exception occurs."""
+        with pytest.raises(RuntimeError):
+            with collector.record_operation("retain", bank_id="test_bank", source="api"):
+                raise RuntimeError("Test error")
+
+        # Should have recorded with success=false
+        call_args = collector.operation_duration.record.call_args
+        attributes = call_args[0][1]
+        assert attributes["success"] == "false"
+
+    def test_record_operation_with_budget(self, collector):
+        """Test that budget is included in attributes when provided."""
+        with collector.record_operation("recall", bank_id="test_bank", source="api", budget="mid"):
+            pass
+
+        call_args = collector.operation_duration.record.call_args
+        attributes = call_args[0][1]
+        assert attributes["budget"] == "mid"
+
+    def test_record_operation_with_max_tokens(self, collector):
+        """Test that max_tokens is included in attributes when provided."""
+        with collector.record_operation("recall", bank_id="test_bank", source="api", max_tokens=4096):
+            pass
+
+        call_args = collector.operation_duration.record.call_args
+        attributes = call_args[0][1]
+        assert attributes["max_tokens"] == "4096"
+
+    def test_record_operation_source_values(self, collector):
+        """Test different source values: api, reflect, internal."""
+        sources = ["api", "reflect", "internal"]
+
+        for source in sources:
+            collector.operation_duration.record.reset_mock()
+
+            with collector.record_operation("recall", bank_id="test_bank", source=source):
+                pass
+
+            call_args = collector.operation_duration.record.call_args
+            attributes = call_args[0][1]
+            assert attributes["source"] == source
+
+    def test_nested_contexts_track_separately(self, collector):
+        """Test that nested operations are tracked separately with different sources."""
+        # Simulate reflect (api) calling recall (reflect)
+        with collector.record_operation("reflect", bank_id="test_bank", source="api"):
+            with collector.record_operation("recall", bank_id="test_bank", source="reflect"):
+                pass
+
+        # Should have 2 calls to record
+        assert collector.operation_duration.record.call_count == 2
+        assert collector.operation_total.add.call_count == 2
+
+        # Check the calls
+        calls = collector.operation_duration.record.call_args_list
+
+        # First call should be recall (inner context exits first)
+        recall_attrs = calls[0][0][1]
+        assert recall_attrs["operation"] == "recall"
+        assert recall_attrs["source"] == "reflect"
+
+        # Second call should be reflect (outer context exits last)
+        reflect_attrs = calls[1][0][1]
+        assert reflect_attrs["operation"] == "reflect"
+        assert reflect_attrs["source"] == "api"
+
+
+class TestGetMetricsCollector:
+    """Tests for the get_metrics_collector function."""
+
+    def test_returns_noop_by_default(self):
+        """Test that get_metrics_collector returns NoOpMetricsCollector by default."""
+        # Reset global state
+        import hindsight_api.metrics as metrics_module
+        original_collector = metrics_module._metrics_collector
+
+        try:
+            metrics_module._metrics_collector = NoOpMetricsCollector()
+            collector = get_metrics_collector()
+            assert isinstance(collector, NoOpMetricsCollector)
+        finally:
+            metrics_module._metrics_collector = original_collector
+
+
+class TestMetricsCollectorBase:
+    """Tests for the MetricsCollectorBase abstract class."""
+
+    def test_is_abstract(self):
+        """Test that MetricsCollectorBase methods are abstract."""
+        # Create a class that inherits but doesn't implement
+        class IncompleteCollector(MetricsCollectorBase):
+            pass
+
+        collector = IncompleteCollector()
+
+        # Abstract methods should raise NotImplementedError
+        with pytest.raises(NotImplementedError):
+            with collector.record_operation("test", "test"):
+                pass
+
+        with pytest.raises(NotImplementedError):
+            collector.record_llm_call("test", "test", "test", 1.0)
+
+
+class TestGetTokenBucket:
+    """Tests for the get_token_bucket function."""
+
+    def test_bucket_0_100(self):
+        """Test tokens < 100 return '0-100' bucket."""
+        assert get_token_bucket(0) == "0-100"
+        assert get_token_bucket(50) == "0-100"
+        assert get_token_bucket(99) == "0-100"
+
+    def test_bucket_100_500(self):
+        """Test tokens 100-499 return '100-500' bucket."""
+        assert get_token_bucket(100) == "100-500"
+        assert get_token_bucket(250) == "100-500"
+        assert get_token_bucket(499) == "100-500"
+
+    def test_bucket_500_1k(self):
+        """Test tokens 500-999 return '500-1k' bucket."""
+        assert get_token_bucket(500) == "500-1k"
+        assert get_token_bucket(750) == "500-1k"
+        assert get_token_bucket(999) == "500-1k"
+
+    def test_bucket_1k_5k(self):
+        """Test tokens 1000-4999 return '1k-5k' bucket."""
+        assert get_token_bucket(1000) == "1k-5k"
+        assert get_token_bucket(2500) == "1k-5k"
+        assert get_token_bucket(4999) == "1k-5k"
+
+    def test_bucket_5k_10k(self):
+        """Test tokens 5000-9999 return '5k-10k' bucket."""
+        assert get_token_bucket(5000) == "5k-10k"
+        assert get_token_bucket(7500) == "5k-10k"
+        assert get_token_bucket(9999) == "5k-10k"
+
+    def test_bucket_10k_50k(self):
+        """Test tokens 10000-49999 return '10k-50k' bucket."""
+        assert get_token_bucket(10000) == "10k-50k"
+        assert get_token_bucket(25000) == "10k-50k"
+        assert get_token_bucket(49999) == "10k-50k"
+
+    def test_bucket_50k_plus(self):
+        """Test tokens >= 50000 return '50k+' bucket."""
+        assert get_token_bucket(50000) == "50k+"
+        assert get_token_bucket(100000) == "50k+"
+        assert get_token_bucket(1000000) == "50k+"
+
+
+class TestLLMMetrics:
+    """Tests for LLM-specific metrics recording."""
+
+    @pytest.fixture
+    def mock_meter(self):
+        """Create a mock meter for testing."""
+        meter = MagicMock()
+        # Create separate mocks for each histogram (operation_duration, llm_duration, http_request_duration)
+        histogram_mocks = [MagicMock(), MagicMock(), MagicMock()]
+        meter.create_histogram.side_effect = histogram_mocks
+        # Create separate mocks for each counter
+        # (operation_total, llm_tokens_input, llm_tokens_output, llm_calls_total, http_requests_total)
+        counter_mocks = [MagicMock() for _ in range(5)]
+        meter.create_counter.side_effect = counter_mocks
+        return meter
+
+    @pytest.fixture
+    def collector(self, mock_meter):
+        """Create a MetricsCollector with a mock meter."""
+        with patch("hindsight_api.metrics.get_meter", return_value=mock_meter):
+            return MetricsCollector()
+
+    def test_record_llm_call_records_duration(self, collector):
+        """Test that record_llm_call records duration."""
+        collector.record_llm_call(
+            provider="openai",
+            model="gpt-4",
+            scope="memory",
+            duration=1.5,
+            input_tokens=100,
+            output_tokens=50,
+            success=True,
+        )
+
+        # LLM duration histogram should be called
+        collector.llm_duration.record.assert_called_once()
+        call_args = collector.llm_duration.record.call_args
+
+        # First arg is duration
+        assert call_args[0][0] == 1.5
+
+        # Second arg is attributes dict
+        attributes = call_args[0][1]
+        assert attributes["provider"] == "openai"
+        assert attributes["model"] == "gpt-4"
+        assert attributes["scope"] == "memory"
+        assert attributes["success"] == "true"
+
+    def test_record_llm_call_records_failure(self, collector):
+        """Test that record_llm_call records failure status."""
+        collector.record_llm_call(
+            provider="anthropic",
+            model="claude-3",
+            scope="reflect",
+            duration=0.5,
+            success=False,
+        )
+
+        # Check success is false
+        call_args = collector.llm_duration.record.call_args
+        attributes = call_args[0][1]
+        assert attributes["success"] == "false"
+
+    def test_record_llm_call_records_tokens_with_buckets(self, collector):
+        """Test that record_llm_call records tokens with bucket labels."""
+        collector.record_llm_call(
+            provider="openai",
+            model="gpt-4",
+            scope="memory",
+            duration=1.0,
+            input_tokens=2500,  # Should be "1k-5k" bucket
+            output_tokens=150,  # Should be "100-500" bucket
+            success=True,
+        )
+
+        # Input tokens should be recorded with bucket
+        collector.llm_tokens_input.add.assert_called_once()
+        input_call = collector.llm_tokens_input.add.call_args
+        assert input_call[0][0] == 2500
+        assert input_call[0][1]["token_bucket"] == "1k-5k"
+
+        # Output tokens should be recorded with bucket
+        collector.llm_tokens_output.add.assert_called_once()
+        output_call = collector.llm_tokens_output.add.call_args
+        assert output_call[0][0] == 150
+        assert output_call[0][1]["token_bucket"] == "100-500"
+
+    def test_record_llm_call_skips_zero_tokens(self, collector):
+        """Test that zero token values don't record."""
+        collector.record_llm_call(
+            provider="openai",
+            model="gpt-4",
+            scope="memory",
+            duration=1.0,
+            input_tokens=0,
+            output_tokens=0,
+            success=True,
+        )
+
+        # Token counters should not be called
+        collector.llm_tokens_input.add.assert_not_called()
+        collector.llm_tokens_output.add.assert_not_called()
+
+    def test_record_llm_call_increments_call_counter(self, collector):
+        """Test that record_llm_call increments the call counter."""
+        collector.record_llm_call(
+            provider="gemini",
+            model="gemini-pro",
+            scope="entity_observation",
+            duration=2.0,
+            success=True,
+        )
+
+        # Call counter should be incremented
+        collector.llm_calls_total.add.assert_called_once()
+        call_args = collector.llm_calls_total.add.call_args
+        assert call_args[0][0] == 1
+        assert call_args[0][1]["provider"] == "gemini"
+        assert call_args[0][1]["model"] == "gemini-pro"
+        assert call_args[0][1]["scope"] == "entity_observation"
+
+    def test_record_llm_call_different_scopes(self, collector):
+        """Test recording LLM calls with different scopes."""
+        scopes = ["memory", "reflect", "entity_observation", "answer"]
+
+        for scope in scopes:
+            collector.llm_duration.record.reset_mock()
+
+            collector.record_llm_call(
+                provider="openai",
+                model="gpt-4",
+                scope=scope,
+                duration=1.0,
+                success=True,
+            )
+
+            call_args = collector.llm_duration.record.call_args
+            attributes = call_args[0][1]
+            assert attributes["scope"] == scope
@@ -0,0 +1,819 @@
+"""
+Tests for MPFP (Meta-Path Forward Push) graph retrieval.
+
+Tests cover:
+1. EdgeCache - lazy caching behavior
+2. mpfp_traverse_async - core traversal algorithm
+3. load_edges_for_frontier - lazy edge loading
+4. rrf_fusion - result fusion
+5. MPFPGraphRetriever - full integration
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+from datetime import datetime, timezone
+
+from hindsight_api.engine.search.mpfp_retrieval import (
+    EdgeCache,
+    EdgeTarget,
+    MPFPConfig,
+    MPFPGraphRetriever,
+    PatternResult,
+    SeedNode,
+    load_all_edges_for_frontier,
+    mpfp_traverse_async,
+    rrf_fusion,
+)
+from hindsight_api.engine.search.types import RetrievalResult
+
+
+class TestEdgeCache:
+    """Tests for the EdgeCache lazy loading cache."""
+
+    def test_empty_cache_returns_empty_neighbors(self):
+        """Empty cache should return empty list for any node."""
+        cache = EdgeCache()
+        neighbors = cache.get_neighbors("semantic", "node-1")
+        assert neighbors == []
+
+    def test_is_fully_loaded_false_for_uncached(self):
+        """is_fully_loaded should return False for nodes not yet loaded."""
+        cache = EdgeCache()
+        assert cache.is_fully_loaded("node-1") is False
+
+    def test_add_all_edges_marks_as_fully_loaded(self):
+        """Adding edges should mark nodes as fully loaded."""
+        cache = EdgeCache()
+
+        edges_by_type = {
+            "semantic": {"node-1": [EdgeTarget("node-2", 0.8), EdgeTarget("node-3", 0.6)]},
+        }
+        cache.add_all_edges(edges_by_type, ["node-1", "node-4"])  # node-4 has no edges
+
+        assert cache.is_fully_loaded("node-1") is True
+        assert cache.is_fully_loaded("node-4") is True  # Marked even with no edges
+        assert cache.is_fully_loaded("node-2") is False  # Target, not source
+
+    def test_get_neighbors_returns_added_edges(self):
+        """get_neighbors should return edges after add_all_edges."""
+        cache = EdgeCache()
+
+        edges_by_type = {
+            "semantic": {"node-1": [EdgeTarget("node-2", 0.8), EdgeTarget("node-3", 0.6)]},
+        }
+        cache.add_all_edges(edges_by_type, ["node-1"])
+
+        neighbors = cache.get_neighbors("semantic", "node-1")
+        assert len(neighbors) == 2
+        assert neighbors[0].node_id == "node-2"
+        assert neighbors[0].weight == 0.8
+
+    def test_get_uncached_filters_loaded_nodes(self):
+        """get_uncached should only return nodes not yet fully loaded."""
+        cache = EdgeCache()
+
+        # Load some nodes (all edge types)
+        cache.add_all_edges({"semantic": {"node-1": []}}, ["node-1", "node-2"])
+
+        # Check uncached
+        uncached = cache.get_uncached(["node-1", "node-2", "node-3", "node-4"])
+        assert set(uncached) == {"node-3", "node-4"}
+
+    def test_get_normalized_neighbors_normalizes_weights(self):
+        """get_normalized_neighbors should normalize weights to sum to 1."""
+        cache = EdgeCache()
+
+        edges_by_type = {
+            "semantic": {
+                "node-1": [
+                    EdgeTarget("node-2", 0.8),
+                    EdgeTarget("node-3", 0.4),
+                    EdgeTarget("node-4", 0.2),
+                ],
+            },
+        }
+        cache.add_all_edges(edges_by_type, ["node-1"])
+
+        # Get top 2, normalized
+        neighbors = cache.get_normalized_neighbors("semantic", "node-1", top_k=2)
+        assert len(neighbors) == 2
+
+        # Weights should sum to 1
+        total = sum(n.weight for n in neighbors)
+        assert abs(total - 1.0) < 0.001
+
+        # node-2 should have higher normalized weight than node-3
+        assert neighbors[0].node_id == "node-2"
+        assert neighbors[1].node_id == "node-3"
+        # Original: 0.8 and 0.4, so normalized: 0.8/1.2 and 0.4/1.2
+        assert abs(neighbors[0].weight - 0.8 / 1.2) < 0.001
+        assert abs(neighbors[1].weight - 0.4 / 1.2) < 0.001
+
+    def test_different_edge_types_are_separate(self):
+        """Different edge types should be stored separately."""
+        cache = EdgeCache()
+
+        edges_by_type = {
+            "semantic": {"node-1": [EdgeTarget("node-2", 0.8)]},
+            "temporal": {"node-1": [EdgeTarget("node-3", 0.5)]},
+        }
+        cache.add_all_edges(edges_by_type, ["node-1"])
+
+        semantic_neighbors = cache.get_neighbors("semantic", "node-1")
+        temporal_neighbors = cache.get_neighbors("temporal", "node-1")
+
+        assert len(semantic_neighbors) == 1
+        assert semantic_neighbors[0].node_id == "node-2"
+
+        assert len(temporal_neighbors) == 1
+        assert temporal_neighbors[0].node_id == "node-3"
+
+
+class TestRRFFusion:
+    """Tests for RRF (Reciprocal Rank Fusion)."""
+
+    def test_empty_results(self):
+        """Empty results should return empty fusion."""
+        fused = rrf_fusion([])
+        assert fused == []
+
+    def test_single_pattern_ranking(self):
+        """Single pattern should preserve ranking order."""
+        result = PatternResult(
+            pattern=["semantic"],
+            scores={"node-1": 0.9, "node-2": 0.7, "node-3": 0.5},
+        )
+
+        fused = rrf_fusion([result], top_k=3)
+        assert len(fused) == 3
+        # node-1 should be first (highest score)
+        assert fused[0][0] == "node-1"
+        assert fused[1][0] == "node-2"
+        assert fused[2][0] == "node-3"
+
+    def test_multiple_patterns_boost_common_nodes(self):
+        """Nodes appearing in multiple patterns should get boosted."""
+        result1 = PatternResult(
+            pattern=["semantic", "semantic"],
+            scores={"node-1": 0.9, "node-2": 0.7},
+        )
+        result2 = PatternResult(
+            pattern=["entity", "temporal"],
+            scores={"node-1": 0.8, "node-3": 0.6},  # node-1 in both
+        )
+
+        fused = rrf_fusion([result1, result2], top_k=3)
+
+        # node-1 should be first (appears in both patterns)
+        assert fused[0][0] == "node-1"
+        # Its score should be higher than others
+        assert fused[0][1] > fused[1][1]
+
+    def test_top_k_limits_results(self):
+        """top_k should limit the number of results."""
+        result = PatternResult(
+            pattern=["semantic"],
+            scores={f"node-{i}": 1.0 / (i + 1) for i in range(10)},
+        )
+
+        fused = rrf_fusion([result], top_k=3)
+        assert len(fused) == 3
+
+    def test_empty_pattern_scores_ignored(self):
+        """Patterns with empty scores should be ignored."""
+        result1 = PatternResult(pattern=["semantic"], scores={})
+        result2 = PatternResult(
+            pattern=["entity"],
+            scores={"node-1": 0.5},
+        )
+
+        fused = rrf_fusion([result1, result2], top_k=3)
+        assert len(fused) == 1
+        assert fused[0][0] == "node-1"
+
+
+class TestMPFPTraverseAsync:
+    """Tests for the async MPFP traversal algorithm."""
+
+    @pytest.mark.asyncio
+    async def test_empty_seeds_returns_empty(self):
+        """Empty seeds should return empty result."""
+        cache = EdgeCache()
+        config = MPFPConfig()
+
+        result = await mpfp_traverse_async(
+            pool=None,  # Not used when no seeds
+            seeds=[],
+            pattern=["semantic"],
+            config=config,
+            cache=cache,
+        )
+
+        assert result.scores == {}
+
+    @pytest.mark.asyncio
+    async def test_single_hop_no_edges(self):
+        """Single hop with no edges should deposit mass at seeds."""
+        cache = EdgeCache()
+        config = MPFPConfig(alpha=0.15, threshold=1e-6)
+
+        # Pre-populate cache with empty edges for seed (marks as fully loaded)
+        cache.add_all_edges({}, ["seed-1"])
+
+        seeds = [SeedNode("seed-1", 1.0)]
+
+        with patch(
+            "hindsight_api.engine.search.mpfp_retrieval.load_all_edges_for_frontier",
+            new_callable=AsyncMock,
+            return_value={},
+        ):
+            result = await mpfp_traverse_async(
+                pool=MagicMock(),
+                seeds=seeds,
+                pattern=["semantic"],
+                config=config,
+                cache=cache,
+            )
+
+        # Seed should have alpha portion of its mass
+        assert "seed-1" in result.scores
+        assert result.scores["seed-1"] == pytest.approx(config.alpha, rel=0.01)
+
+    @pytest.mark.asyncio
+    async def test_single_hop_with_edges(self):
+        """Single hop should spread mass to neighbors."""
+        cache = EdgeCache()
+        config = MPFPConfig(alpha=0.15, threshold=1e-6, top_k_neighbors=10)
+
+        seeds = [SeedNode("seed-1", 1.0)]
+
+        # Pre-populate cache with seed edges (mimics pre-warming in retrieve())
+        cache.add_all_edges(
+            {
+                "semantic": {
+                    "seed-1": [
+                        EdgeTarget("neighbor-1", 0.8),
+                        EdgeTarget("neighbor-2", 0.4),
+                    ]
+                }
+            },
+            ["seed-1"],
+        )
+
+        # Mock for loading neighbor edges (after hop 0)
+        async def mock_load_all_edges(pool, node_ids, top_k=20):
+            return {}
+
+        with patch(
+            "hindsight_api.engine.search.mpfp_retrieval.load_all_edges_for_frontier",
+            side_effect=mock_load_all_edges,
+        ):
+            result = await mpfp_traverse_async(
+                pool=MagicMock(),
+                seeds=seeds,
+                pattern=["semantic"],
+                config=config,
+                cache=cache,
+            )
+
+        # Seed keeps alpha portion
+        assert "seed-1" in result.scores
+        assert result.scores["seed-1"] == pytest.approx(config.alpha, rel=0.01)
+
+        # Neighbors get remaining mass (normalized)
+        assert "neighbor-1" in result.scores
+        assert "neighbor-2" in result.scores
+
+        # neighbor-1 should get more (higher weight)
+        assert result.scores["neighbor-1"] > result.scores["neighbor-2"]
+
+    @pytest.mark.asyncio
+    async def test_two_hops(self):
+        """Two-hop pattern should traverse through neighbors."""
+        cache = EdgeCache()
+        config = MPFPConfig(alpha=0.15, threshold=1e-6, top_k_neighbors=10)
+
+        seeds = [SeedNode("seed-1", 1.0)]
+
+        # Pre-populate cache with seed edges (mimics pre-warming in retrieve())
+        cache.add_all_edges(
+            {"semantic": {"seed-1": [EdgeTarget("hop1-node", 1.0)]}},
+            ["seed-1"],
+        )
+
+        # Mock edge loading for hop 1 nodes
+        async def mock_load_all_edges(pool, node_ids, top_k=20):
+            edges: dict[str, dict[str, list[EdgeTarget]]] = {"semantic": {}}
+            if "hop1-node" in node_ids:
+                edges["semantic"]["hop1-node"] = [EdgeTarget("hop2-node", 1.0)]
+            return edges
+
+        with patch(
+            "hindsight_api.engine.search.mpfp_retrieval.load_all_edges_for_frontier",
+            side_effect=mock_load_all_edges,
+        ):
+            result = await mpfp_traverse_async(
+                pool=MagicMock(),
+                seeds=seeds,
+                pattern=["semantic", "semantic"],  # Two hops
+                config=config,
+                cache=cache,
+            )
+
+        # Should have scores for all three nodes
+        assert "seed-1" in result.scores
+        assert "hop1-node" in result.scores
+        assert "hop2-node" in result.scores
+
+    @pytest.mark.asyncio
+    async def test_cache_reuse(self):
+        """Cache should prevent redundant edge loading for already-cached nodes."""
+        cache = EdgeCache()
+        config = MPFPConfig(alpha=0.15, threshold=1e-6)
+
+        # Pre-load cache (marks seed-1 AND neighbor-1 as fully loaded)
+        # neighbor-1 is also cached because after hop 0, the frontier contains neighbor-1
+        # and the algorithm tries to pre-warm edges for the next hop
+        cache.add_all_edges(
+            {"semantic": {"seed-1": [EdgeTarget("neighbor-1", 1.0)], "neighbor-1": []}},
+            ["seed-1", "neighbor-1"],
+        )
+
+        seeds = [SeedNode("seed-1", 1.0)]
+
+        load_mock = AsyncMock(return_value={})
+
+        with patch(
+            "hindsight_api.engine.search.mpfp_retrieval.load_all_edges_for_frontier",
+            load_mock,
+        ):
+            await mpfp_traverse_async(
+                pool=MagicMock(),
+                seeds=seeds,
+                pattern=["semantic"],
+                config=config,
+                cache=cache,
+            )
+
+        # Should not call load_all_edges_for_frontier since all nodes are already cached
+        load_mock.assert_not_called()
+
+
+class TestMPFPGraphRetriever:
+    """Tests for the MPFPGraphRetriever class."""
+
+    def test_name_is_mpfp(self):
+        """Retriever name should be 'mpfp'."""
+        retriever = MPFPGraphRetriever()
+        assert retriever.name == "mpfp"
+
+    def test_default_config(self):
+        """Default config should have expected patterns."""
+        # Use explicit config to avoid global config dependency
+        config = MPFPConfig()
+        retriever = MPFPGraphRetriever(config=config)
+
+        assert len(retriever.config.patterns_semantic) > 0
+        assert len(retriever.config.patterns_temporal) > 0
+        assert retriever.config.alpha == 0.15
+        assert retriever.config.top_k_neighbors == 20
+
+    def test_custom_config(self):
+        """Custom config should be used."""
+        config = MPFPConfig(alpha=0.3, top_k_neighbors=10)
+        retriever = MPFPGraphRetriever(config=config)
+
+        assert retriever.config.alpha == 0.3
+        assert retriever.config.top_k_neighbors == 10
+
+    def test_convert_seeds_from_retrieval_results(self):
+        """_convert_seeds should extract scores from RetrievalResult."""
+        retriever = MPFPGraphRetriever()
+
+        results = [
+            RetrievalResult(id="id-1", text="text1", fact_type="world", similarity=0.9),
+            RetrievalResult(id="id-2", text="text2", fact_type="world", similarity=0.7),
+        ]
+
+        seeds = retriever._convert_seeds(results, "similarity")
+
+        assert len(seeds) == 2
+        assert seeds[0].node_id == "id-1"
+        assert seeds[0].score == 0.9
+        assert seeds[1].node_id == "id-2"
+        assert seeds[1].score == 0.7
+
+    def test_convert_seeds_empty(self):
+        """_convert_seeds should handle empty/None input."""
+        retriever = MPFPGraphRetriever()
+
+        assert retriever._convert_seeds(None, "similarity") == []
+        assert retriever._convert_seeds([], "similarity") == []
+
+    @pytest.mark.asyncio
+    async def test_retrieve_no_seeds_returns_empty(self):
+        """Retrieve with no seeds should return empty results."""
+        # Use explicit config to avoid global config dependency
+        config = MPFPConfig()
+        retriever = MPFPGraphRetriever(config=config)
+
+        # Mock _find_semantic_seeds to return empty
+        with patch.object(retriever, "_find_semantic_seeds", new_callable=AsyncMock, return_value=[]):
+            results, timings = await retriever.retrieve(
+                pool=MagicMock(),
+                query_embedding_str="[0.1, 0.2]",
+                bank_id="test",
+                fact_type="world",
+                budget=10,
+            )
+
+        assert results == []
+        assert timings is not None
+        assert timings.pattern_count == 0
+
+    @pytest.mark.asyncio
+    async def test_retrieve_with_semantic_seeds(self):
+        """Retrieve with semantic seeds should run patterns and return results."""
+        # Use explicit config to avoid global config dependency
+        config = MPFPConfig()
+        retriever = MPFPGraphRetriever(config=config)
+
+        semantic_seeds = [
+            RetrievalResult(id="seed-1", text="seed text", fact_type="world", similarity=0.9),
+        ]
+
+        # Mock the internal functions
+        # mpfp_traverse_hop_synchronized returns a list of PatternResult (one per pattern)
+        async def mock_traverse(*args, **kwargs):
+            return [PatternResult(pattern=["semantic"], scores={"seed-1": 0.5, "result-1": 0.3})]
+
+        async def mock_fetch(pool, node_ids, fact_type):
+            return [
+                RetrievalResult(id="seed-1", text="seed text", fact_type="world"),
+                RetrievalResult(id="result-1", text="result text", fact_type="world"),
+            ]
+
+        with (
+            patch(
+                "hindsight_api.engine.search.mpfp_retrieval.mpfp_traverse_hop_synchronized",
+                side_effect=mock_traverse,
+            ),
+            patch(
+                "hindsight_api.engine.search.mpfp_retrieval.fetch_memory_units_by_ids",
+                side_effect=mock_fetch,
+            ),
+            patch(
+                "hindsight_api.engine.search.mpfp_retrieval.load_all_edges_for_frontier",
+                new_callable=AsyncMock,
+                return_value={},
+            ),
+        ):
+            results, timings = await retriever.retrieve(
+                pool=MagicMock(),
+                query_embedding_str="[0.1, 0.2]",
+                bank_id="test",
+                fact_type="world",
+                budget=10,
+                semantic_seeds=semantic_seeds,
+            )
+
+        assert len(results) == 2
+        assert timings is not None
+        assert timings.pattern_count > 0
+
+
+@pytest.mark.asyncio
+async def test_mpfp_integration(memory, request_context):
+    """Integration test: MPFP retrieval with real database."""
+    bank_id = f"test_mpfp_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store memories with entity relationships
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice works at TechCorp as a software engineer",
+            context="employee info",
+            request_context=request_context,
+        )
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="TechCorp is located in San Francisco",
+            context="company info",
+            request_context=request_context,
+        )
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Bob is Alice's manager at TechCorp",
+            context="employee info",
+            request_context=request_context,
+        )
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="San Francisco has many tech companies",
+            context="city info",
+            request_context=request_context,
+        )
+
+        # Query should find related facts via graph traversal
+        from hindsight_api.engine.memory_engine import Budget
+
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="Tell me about Alice",
+            fact_type=["world"],
+            budget=Budget.MID,
+            max_tokens=2048,
+            request_context=request_context,
+        )
+
+        # Should return results
+        assert result.results is not None
+        assert len(result.results) > 0
+
+        # Should find Alice-related facts
+        fact_texts = [f.text for f in result.results]
+        alice_facts = [t for t in fact_texts if "Alice" in t or "TechCorp" in t]
+        assert len(alice_facts) > 0, f"Should find Alice-related facts, got: {fact_texts}"
+
+        print(f"\n✓ MPFP integration test passed! Found {len(result.results)} facts")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_mpfp_lazy_loading_efficiency(memory, request_context):
+    """Test that MPFP loads edges lazily, not upfront."""
+    bank_id = f"test_mpfp_lazy_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store many memories to create a larger graph
+        for i in range(20):
+            await memory.retain_async(
+                bank_id=bank_id,
+                content=f"Fact number {i} about topic {i % 5}",
+                context=f"context {i}",
+                request_context=request_context,
+            )
+
+        from hindsight_api.engine.memory_engine import Budget
+
+        # Query - MPFP should only load edges for relevant frontier nodes
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="topic 0",
+            fact_type=["world"],
+            budget=Budget.LOW,
+            max_tokens=1024,
+            enable_trace=True,
+            request_context=request_context,
+        )
+
+        assert result.results is not None
+
+        # Check trace for timing info
+        if result.trace:
+            print(f"\n✓ MPFP lazy loading test passed!")
+            print(f"  - Facts returned: {len(result.results)}")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+# ============================================================================
+# MPFP Performance Benchmark Tests
+# ============================================================================
+# These tests require an external database with a large memory bank to be useful.
+# Set EXTERNAL_DATABASE_URL and BENCHMARK_BANK_ID environment variables to run.
+# Example:
+#   EXTERNAL_DATABASE_URL=postgresql://user:pass@host:port/db \
+#   BENCHMARK_BANK_ID=load-test \
+#   pytest tests/test_mpfp_retrieval.py::test_mpfp_edge_loading_performance -v -s
+
+
+import os
+import asyncpg
+
+EXTERNAL_DATABASE_URL = os.environ.get("EXTERNAL_DATABASE_URL")
+BENCHMARK_BANK_ID = os.environ.get("BENCHMARK_BANK_ID", "load-test")
+
+requires_external_db = pytest.mark.skipif(
+    EXTERNAL_DATABASE_URL is None,
+    reason="EXTERNAL_DATABASE_URL not set - skipping external DB benchmark",
+)
+
+
+@requires_external_db
+@pytest.mark.asyncio
+async def test_mpfp_edge_loading_performance():
+    """
+    Benchmark MPFP edge loading performance.
+
+    This test measures the performance of the LATERAL query optimization
+    for loading edges in the MPFP graph traversal algorithm.
+
+    Set EXTERNAL_DATABASE_URL to point to a database with existing data.
+    Set BENCHMARK_BANK_ID to specify which bank to query (default: load-test).
+
+    Example usage:
+        EXTERNAL_DATABASE_URL=postgresql://hindsight:hindsight@localhost:5435/hindsight \
+        BENCHMARK_BANK_ID=load-test \
+        pytest tests/test_mpfp_retrieval.py::test_mpfp_edge_loading_performance -v -s
+    """
+    import time
+
+    # Connect to external database
+    pool = await asyncpg.create_pool(EXTERNAL_DATABASE_URL, min_size=2, max_size=10)
+
+    try:
+        # Get some sample node IDs from the database
+        async with pool.acquire() as conn:
+            # First check how many links exist
+            stats = await conn.fetchrow("""
+                SELECT
+                    count(*) as total_links,
+                    count(DISTINCT from_unit_id) as unique_sources
+                FROM memory_links
+            """)
+            print(f"\n📊 Database Stats:")
+            print(f"   Total links: {stats['total_links']:,}")
+            print(f"   Unique sources: {stats['unique_sources']:,}")
+
+            # Get edge distribution by type
+            type_stats = await conn.fetch("""
+                SELECT link_type, count(*) as cnt,
+                       round(avg(weight)::numeric, 3) as avg_weight
+                FROM memory_links
+                GROUP BY link_type
+                ORDER BY cnt DESC
+            """)
+            print(f"\n   Edge distribution:")
+            for row in type_stats:
+                print(f"     - {row['link_type']}: {row['cnt']:,} (avg_weight={row['avg_weight']})")
+
+            # Get sample frontier nodes (from memory_units in the benchmark bank)
+            # bank_id is the text primary key in banks table
+            frontier_rows = await conn.fetch("""
+                SELECT id FROM memory_units
+                WHERE bank_id = $1
+                LIMIT 100
+            """, BENCHMARK_BANK_ID)
+
+            if not frontier_rows:
+                pytest.skip(f"No memory units found for bank '{BENCHMARK_BANK_ID}'")
+
+            frontier_node_ids = [str(row['id']) for row in frontier_rows]
+            print(f"\n🎯 Testing with {len(frontier_node_ids)} frontier nodes from bank '{BENCHMARK_BANK_ID}'")
+
+        # Test 1: Original query approach (all edges, no per-type limit)
+        async with pool.acquire() as conn:
+            start = time.time()
+            original_rows = await conn.fetch("""
+                SELECT ml.from_unit_id, ml.to_unit_id, ml.link_type, ml.weight
+                FROM memory_links ml
+                WHERE ml.from_unit_id = ANY($1::uuid[])
+                  AND ml.weight >= 0.1
+                ORDER BY ml.from_unit_id, ml.link_type, ml.weight DESC
+            """, frontier_node_ids)
+            original_time = time.time() - start
+            original_count = len(original_rows)
+
+        # Test 2: New LATERAL query approach (top-k per type)
+        async with pool.acquire() as conn:
+            start = time.time()
+            lateral_rows = await conn.fetch("""
+                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 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 20
+                ) edges
+            """, frontier_node_ids)
+            lateral_time = time.time() - start
+            lateral_count = len(lateral_rows)
+
+        # Print results
+        print(f"\n⏱️  Performance Comparison ({len(frontier_node_ids)} nodes):")
+        print(f"\n   Original (all edges):")
+        print(f"     - Time: {original_time * 1000:.2f}ms")
+        print(f"     - Rows: {original_count:,}")
+        print(f"     - Rows/node: {original_count / len(frontier_node_ids):.1f}")
+
+        print(f"\n   LATERAL (top-20 per type):")
+        print(f"     - Time: {lateral_time * 1000:.2f}ms")
+        print(f"     - Rows: {lateral_count:,}")
+        print(f"     - Rows/node: {lateral_count / len(frontier_node_ids):.1f}")
+
+        speedup = original_time / lateral_time if lateral_time > 0 else float('inf')
+        reduction = (1 - lateral_count / original_count) * 100 if original_count > 0 else 0
+        print(f"\n   📈 Improvement:")
+        print(f"     - Speedup: {speedup:.2f}x faster")
+        print(f"     - Data reduction: {reduction:.1f}% fewer rows")
+
+        # Assert improvement (should be at least some improvement for large datasets)
+        if original_count > 1000:
+            # For large datasets, expect significant improvement
+            assert speedup >= 1.5, f"Expected at least 1.5x speedup, got {speedup:.2f}x"
+            assert reduction >= 30, f"Expected at least 30% data reduction, got {reduction:.1f}%"
+            print(f"\n✅ Performance test PASSED!")
+        else:
+            print(f"\n⚠️ Dataset too small ({original_count} rows) for meaningful performance comparison")
+
+    finally:
+        await pool.close()
+
+
+@requires_external_db
+@pytest.mark.asyncio
+async def test_mpfp_full_retrieval_performance():
+    """
+    Benchmark full MPFP retrieval including traversal and reranking.
+
+    This test measures end-to-end MPFP retrieval performance.
+    """
+    import time
+
+    pool = await asyncpg.create_pool(EXTERNAL_DATABASE_URL, min_size=2, max_size=10)
+
+    try:
+        # Get a sample query embedding from an existing memory unit
+        async with pool.acquire() as conn:
+            # Check if bank exists
+            bank_exists = await conn.fetchval("""
+                SELECT 1 FROM banks WHERE bank_id = $1
+            """, BENCHMARK_BANK_ID)
+            if not bank_exists:
+                pytest.skip(f"Bank '{BENCHMARK_BANK_ID}' not found")
+
+            sample = await conn.fetchrow("""
+                SELECT embedding::text as embedding_str
+                FROM memory_units
+                WHERE bank_id = $1
+                  AND embedding IS NOT NULL
+                LIMIT 1
+            """, BENCHMARK_BANK_ID)
+
+            if not sample:
+                pytest.skip("No memory units with embeddings found")
+
+            query_embedding_str = sample['embedding_str']
+
+        # Run MPFP retrieval
+        retriever = MPFPGraphRetriever()
+
+        print(f"\n🔍 Running MPFP retrieval benchmark on bank '{BENCHMARK_BANK_ID}'...")
+
+        # Warm-up run
+        await retriever.retrieve(
+            pool=pool,
+            query_embedding_str=query_embedding_str,
+            bank_id=BENCHMARK_BANK_ID,
+            fact_type="world",
+            budget=100,
+            query_text="test query",
+        )
+
+        # Timed runs
+        timings_list = []
+        for i in range(3):
+            start = time.time()
+            results, timings = await retriever.retrieve(
+                pool=pool,
+                query_embedding_str=query_embedding_str,
+                bank_id=BENCHMARK_BANK_ID,
+                fact_type="opinion",
+                budget=100,
+                query_text="What did I say about training models?",
+            )
+            elapsed = time.time() - start
+            timings_list.append((elapsed, timings, len(results)))
+
+        # Print results
+        print(f"\n⏱️  MPFP Retrieval Results (3 runs):")
+        for i, (elapsed, timings, count) in enumerate(timings_list):
+            print(f"\n   Run {i + 1}:")
+            print(f"     - Total: {elapsed * 1000:.2f}ms")
+            print(f"     - Results: {count}")
+            if timings:
+                print(f"     - Seeds: {timings.seeds_time * 1000:.2f}ms")
+                print(f"     - Patterns: {timings.pattern_count}")
+                print(f"     - Traverse: {timings.traverse * 1000:.2f}ms")
+                print(f"     - Edge load: {timings.edge_load_time * 1000:.2f}ms")
+                print(f"     - Edges: {timings.edge_count:,}")
+                print(f"     - DB queries: {timings.db_queries}")
+                print(f"     - Fusion: {timings.fusion * 1000:.2f}ms")
+                print(f"     - Fetch: {timings.fetch * 1000:.2f}ms")
+
+        avg_time = sum(t[0] for t in timings_list) / len(timings_list)
+        print(f"\n   📊 Average: {avg_time * 1000:.2f}ms")
+        print(f"\n✅ MPFP retrieval benchmark complete!")
+
+    finally:
+        await pool.close()
@@ -0,0 +1,336 @@
+"""
+Test multilingual support for retain and reflect operations.
+
+Tests that the system correctly handles non-English input and produces
+output in the same language as the input.
+"""
+
+import pytest
+import logging
+from datetime import datetime, timezone
+from hindsight_api.engine.memory_engine import Budget
+from hindsight_api import RequestContext
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.mark.asyncio
+async def test_retain_chinese_content(memory, request_context):
+    """
+    Test that retain correctly extracts facts from Chinese content
+    and keeps the output in Chinese.
+
+    This test verifies:
+    1. Facts are extracted from Chinese text
+    2. The extracted facts contain Chinese characters
+    3. Entity names are preserved in Chinese
+    """
+    bank_id = f"test_chinese_retain_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Chinese content about a person and their activities
+        chinese_content = """
+        张伟是一位资深软件工程师，在腾讯工作了五年。他专门研究分布式系统，
+        并领导了公司微服务架构的开发。他以编写干净、文档完善的代码而闻名。
+
+        李明上个月加入团队担任初级开发人员。他正在学习React和Node.js。
+        李明很有热情，在代码审查中提出很好的问题。他最近完成了他的第一个功能，
+        这是一个用户认证流程。
+
+        团队使用Kubernetes进行容器编排，并部署到阿里云。他们遵循敏捷方法论，
+        采用两周冲刺周期。合并前必须进行代码审查。
+        """
+
+        # Retain the Chinese content
+        unit_ids = await memory.retain_async(
+            bank_id=bank_id,
+            content=chinese_content,
+            context="团队概述",  # Chinese context
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        logger.info(f"Retained {len(unit_ids)} facts from Chinese content")
+        assert len(unit_ids) > 0, "Should have extracted and stored facts from Chinese content"
+
+        # Recall the facts with a Chinese query
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="告诉我关于张伟的信息",  # "Tell me about Zhang Wei"
+            budget=Budget.MID,
+            max_tokens=1000,
+            fact_type=["world"],
+            request_context=request_context,
+        )
+
+        logger.info(f"Recalled {len(result.results)} facts")
+        assert len(result.results) > 0, "Should recall facts about Zhang Wei"
+
+        # Verify that the facts contain Chinese characters
+        # At least one fact should mention 张伟 (Zhang Wei) or related Chinese content
+        chinese_facts_found = 0
+        for fact in result.results:
+            logger.info(f"Fact: {fact.text[:100]}...")
+            # Check for common Chinese characters or the name
+            if any(
+                char in fact.text
+                for char in ["张", "伟", "腾讯", "软件", "工程师", "分布式", "系统", "代码"]
+            ):
+                chinese_facts_found += 1
+
+        logger.info(f"Found {chinese_facts_found} facts with Chinese content")
+        assert chinese_facts_found > 0, (
+            f"Expected facts to contain Chinese characters, but none found. "
+            f"Facts: {[f.text for f in result.results]}"
+        )
+
+        logger.info("Chinese retain test passed - facts preserved in Chinese")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_reflect_chinese_content(memory, request_context):
+    """
+    Test that reflect correctly generates responses in Chinese
+    when given Chinese facts and a Chinese query.
+
+    This test verifies:
+    1. Reflection produces a response in Chinese
+    2. The response references the Chinese facts
+    3. Opinions are formed and expressed in Chinese
+
+    Note: LLM responses are non-deterministic, so we retry up to 3 times
+    to account for occasional hallucinations of different names.
+    """
+    bank_id = f"test_chinese_reflect_{datetime.now(timezone.utc).timestamp()}"
+    max_retries = 3
+
+    try:
+        # Store some Chinese facts to give context for opinion formation
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="张伟是一位优秀的软件工程师，完成了五个重大项目。他总是按时交付，代码整洁有良好的文档。",
+            context="绩效评估",  # "Performance review"
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="李明最近加入团队。他错过了第一个截止日期，代码有很多bug。",
+            context="绩效评估",
+            event_date=datetime(2024, 2, 1, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        last_error = None
+        for attempt in range(max_retries):
+            try:
+                # Reflect with a Chinese query
+                query = "谁是更可靠的工程师？"  # "Who is a more reliable engineer?"
+                result = await memory.reflect_async(
+                    bank_id=bank_id,
+                    query=query,
+                    budget=Budget.LOW,
+                    request_context=request_context,
+                )
+
+                logger.info(f"Reflection answer (attempt {attempt + 1}): {result.text}")
+
+                # Verify we got an answer
+                assert result.text, "Reflection should return an answer"
+
+                # Check that the response contains Chinese characters
+                # The response should be in Chinese, not English
+                chinese_chars_found = sum(1 for char in result.text if "\u4e00" <= char <= "\u9fff")
+                total_chars = len(result.text.replace(" ", "").replace("\n", ""))
+
+                logger.info(f"Chinese characters: {chinese_chars_found}, Total characters: {total_chars}")
+
+                # At least 30% of characters should be Chinese (allowing for numbers, punctuation)
+                chinese_ratio = chinese_chars_found / max(total_chars, 1)
+                assert chinese_ratio > 0.3, (
+                    f"Expected response to be in Chinese (>30% Chinese characters), "
+                    f"but only {chinese_ratio:.1%} are Chinese. Response: {result.text}"
+                )
+
+                # Check that Chinese names are mentioned
+                # The LLM should use names from the based_on facts, not hallucinate different names
+                # Extract Chinese names from the based_on world facts
+                expected_names = set()
+                for fact in result.based_on.get("world", []):
+                    # Extract Chinese entity names from the fact
+                    for entity in (fact.entities or []):
+                        # Check if entity contains Chinese characters
+                        if any("\u4e00" <= char <= "\u9fff" for char in entity):
+                            expected_names.add(entity)
+
+                # Also check for the specific names we stored
+                expected_names.update(["张伟", "李明"])
+
+                # At least one expected name should appear in the response
+                found_name = any(name in result.text for name in expected_names)
+                assert found_name, (
+                    f"Expected response to mention one of the Chinese names: {expected_names}. Response: {result.text}"
+                )
+
+                logger.info("Chinese reflect test passed - response generated in Chinese")
+                return  # Test passed, exit
+
+            except AssertionError as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    logger.warning(f"Attempt {attempt + 1} failed: {e}. Retrying...")
+                    continue
+                else:
+                    raise e
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_retain_japanese_content(memory, request_context):
+    """
+    Test that retain correctly handles Japanese content.
+
+    This test verifies multilingual support extends beyond Chinese
+    to other non-Latin languages.
+
+    Note: LLM fact extraction is non-deterministic and may sometimes translate
+    content to English despite instructions. We retry up to 3 times.
+    """
+    max_retries = 3
+    last_error = None
+
+    for attempt in range(max_retries):
+        # Use unique bank_id per attempt to avoid stale data
+        bank_id = f"test_japanese_retain_{datetime.now(timezone.utc).timestamp()}_{attempt}"
+
+        try:
+            # Japanese content about a developer
+            japanese_content = """
+            田中さんはソフトウェアエンジニアで、東京のスタートアップで働いています。
+            彼女はPythonとTypeScriptが得意で、毎日コードレビューをしています。
+            先週、新しいAPIを完成させました。
+            """
+
+            unit_ids = await memory.retain_async(
+                bank_id=bank_id,
+                content=japanese_content,
+                context="チームプロフィール",  # "Team profile"
+                event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+                request_context=request_context,
+            )
+
+            logger.info(f"Retained {len(unit_ids)} facts from Japanese content (attempt {attempt + 1})")
+            assert len(unit_ids) > 0, "Should have extracted facts from Japanese content"
+
+            # Recall with Japanese query
+            result = await memory.recall_async(
+                bank_id=bank_id,
+                query="田中さんについて教えてください",  # "Tell me about Tanaka-san"
+                budget=Budget.MID,
+                max_tokens=1000,
+                fact_type=["world"],
+                request_context=request_context,
+            )
+
+            assert len(result.results) > 0, "Should recall facts about Tanaka"
+
+            # Check for Japanese content in facts
+            japanese_facts_found = 0
+            for fact in result.results:
+                logger.info(f"Fact: {fact.text[:100]}...")
+                # Check for Japanese characters (hiragana, katakana, or kanji)
+                if any(
+                    ("\u3040" <= char <= "\u309f")  # Hiragana
+                    or ("\u30a0" <= char <= "\u30ff")  # Katakana
+                    or ("\u4e00" <= char <= "\u9fff")  # Kanji
+                    for char in fact.text
+                ):
+                    japanese_facts_found += 1
+
+            assert japanese_facts_found > 0, (
+                f"Expected facts to contain Japanese characters. "
+                f"Facts: {[f.text for f in result.results]}"
+            )
+
+            logger.info("Japanese retain test passed - facts preserved in Japanese")
+            return  # Test passed
+
+        except AssertionError as e:
+            last_error = e
+            if attempt < max_retries - 1:
+                logger.warning(f"Attempt {attempt + 1} failed: {e}. Retrying...")
+            else:
+                raise e
+        finally:
+            # Cleanup the bank
+            try:
+                await memory.delete_bank(bank_id, request_context=request_context)
+            except Exception:
+                pass
+
+
+@pytest.mark.asyncio
+async def test_mixed_language_entities(memory, request_context):
+    """
+    Test that entity extraction works correctly with mixed language content.
+
+    Some entities (like company names) might be in English while the
+    description is in Chinese.
+    """
+    bank_id = f"test_mixed_lang_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Mixed language content - Chinese with English company names
+        mixed_content = """
+        王芳在Google北京办公室工作，她是一名高级产品经理。
+        之前她在Microsoft和Amazon工作过。
+        她负责管理YouTube在中国市场的推广策略。
+        """
+
+        unit_ids = await memory.retain_async(
+            bank_id=bank_id,
+            content=mixed_content,
+            context="员工资料",
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        assert len(unit_ids) > 0, "Should extract facts from mixed language content"
+
+        # Recall and check entities
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="王芳在哪里工作？",  # "Where does Wang Fang work?"
+            budget=Budget.MID,
+            max_tokens=1000,
+            fact_type=["world"],
+            include_entities=True,
+            request_context=request_context,
+        )
+
+        assert len(result.results) > 0, "Should recall facts about Wang Fang"
+
+        # Check that both Chinese and English entities are preserved
+        all_text = " ".join(f.text for f in result.results)
+        logger.info(f"Combined facts: {all_text}")
+
+        # Should contain Chinese name and/or English company names
+        has_chinese_name = "王芳" in all_text
+        has_english_company = any(
+            company in all_text for company in ["Google", "Microsoft", "Amazon", "YouTube"]
+        )
+
+        assert has_chinese_name or has_english_company, (
+            f"Expected mixed language entities. Facts: {all_text}"
+        )
+
+        logger.info("Mixed language entity test passed")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
@@ -173,6 +173,107 @@ async def test_regenerate_entity_observations(memory, request_context):
            await conn.execute("DELETE FROM entities WHERE bank_id = $1", bank_id)


+@pytest.mark.asyncio
+async def test_manual_regenerate_with_few_facts(memory, request_context):
+    """
+    Test that manual regeneration works even with fewer than 5 facts.
+
+    This is important because:
+    - Automatic generation during retain requires MIN_FACTS_THRESHOLD (5)
+    - But manual regeneration via API should work with any number of facts
+    - The UI triggers manual regeneration, so it should work regardless of fact count
+    """
+    bank_id = f"test_manual_regen_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store only 2 facts - below the automatic threshold
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice works at Google as a senior software engineer.",
+            context="work info",
+            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice loves hiking and outdoor photography.",
+            context="hobbies",
+            event_date=datetime(2024, 1, 16, tzinfo=timezone.utc),
+            request_context=request_context,
+        )
+
+        # Find the Alice entity
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            entity_row = await conn.fetchrow(
+                """
+                SELECT id, canonical_name
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%alice%'
+                LIMIT 1
+                """,
+                bank_id
+            )
+
+        assert entity_row is not None, "Alice entity should have been extracted"
+
+        entity_id = str(entity_row['id'])
+        entity_name = entity_row['canonical_name']
+
+        # Check fact count - should be < 5
+        async with pool.acquire() as conn:
+            fact_count = await conn.fetchval(
+                "SELECT COUNT(*) FROM unit_entities WHERE entity_id = $1",
+                entity_row['id']
+            )
+
+        print(f"\n=== Manual Regeneration Test ===")
+        print(f"Entity: {entity_name} (id: {entity_id})")
+        print(f"Linked facts: {fact_count}")
+
+        # Verify we're testing with fewer than the automatic threshold
+        assert fact_count < 5, f"Test requires < 5 facts, but entity has {fact_count}"
+
+        # Before regeneration - should have no observations (auto threshold not met)
+        obs_before = await memory.get_entity_observations(bank_id, entity_id, limit=10, request_context=request_context)
+        print(f"Observations before manual regenerate: {len(obs_before)}")
+
+        # Manually regenerate observations - this should work regardless of fact count
+        created_ids = await memory.regenerate_entity_observations(
+            bank_id=bank_id,
+            entity_id=entity_id,
+            entity_name=entity_name,
+            request_context=request_context,
+        )
+
+        print(f"Observations created by manual regenerate: {len(created_ids)}")
+
+        # Get observations after regeneration
+        observations = await memory.get_entity_observations(bank_id, entity_id, limit=10, request_context=request_context)
+        print(f"Observations after manual regenerate: {len(observations)}")
+        for obs in observations:
+            print(f"  - {obs.text}")
+
+        # Manual regeneration should create observations even with < 5 facts
+        assert len(observations) > 0, \
+            f"Manual regeneration should create observations even with only {fact_count} facts. " \
+            f"The LLM should synthesize at least 1 observation from the available facts."
+
+        # Verify observations contain relevant content
+        obs_texts = " ".join([o.text.lower() for o in observations])
+        assert any(keyword in obs_texts for keyword in ["google", "engineer", "hiking", "photography", "alice"]), \
+            "Observations should contain relevant information about Alice"
+
+        print(f"✓ Manual regeneration works with {fact_count} facts (below automatic threshold of 5)")
+
+    finally:
+        # Cleanup
+        pool = await memory._get_pool()
+        async with pool.acquire() as conn:
+            await conn.execute("DELETE FROM memory_units WHERE bank_id = $1", bank_id)
+            await conn.execute("DELETE FROM entities WHERE bank_id = $1", bank_id)
+
+
@pytest.mark.asyncio
 async def test_search_with_include_entities(memory, request_context):
    """
@@ -0,0 +1,277 @@
+"""
+Tests for per-operation LLM configuration.
+
+Verifies that retain and reflect operations use their respective LLM configs.
+"""
+
+import os
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def setup_test_env():
+    """Set up environment for each test, restoring original values after."""
+    from hindsight_api.config import clear_config_cache
+
+    # Save original environment values
+    env_vars_to_set = {
+        "HINDSIGHT_API_SKIP_LLM_VERIFICATION": "true",
+        "HINDSIGHT_API_LAZY_RERANKER": "true",
+        "HINDSIGHT_API_LLM_PROVIDER": "mock",
+        "HINDSIGHT_API_LLM_MODEL": "default-model",
+        "HINDSIGHT_API_RETAIN_LLM_PROVIDER": "mock",
+        "HINDSIGHT_API_RETAIN_LLM_MODEL": "retain-model",
+        "HINDSIGHT_API_REFLECT_LLM_PROVIDER": "mock",
+        "HINDSIGHT_API_REFLECT_LLM_MODEL": "reflect-model",
+    }
+
+    # Save original values
+    original_values = {}
+    for key in env_vars_to_set:
+        original_values[key] = os.environ.get(key)
+
+    # Set test values
+    for key, value in env_vars_to_set.items():
+        os.environ[key] = value
+
+    clear_config_cache()
+
+    yield
+
+    # Restore original environment
+    for key, original_value in original_values.items():
+        if original_value is None:
+            os.environ.pop(key, None)
+        else:
+            os.environ[key] = original_value
+
+    clear_config_cache()
+
+
+class TestPerOperationLLMConfig:
+    """Test that per-operation LLM configs are correctly applied."""
+
+    def test_config_loads_per_operation_settings(self):
+        """Test that config correctly loads per-operation LLM settings."""
+        from hindsight_api.config import get_config
+
+        config = get_config()
+
+        # Default config
+        assert config.llm_provider == "mock"
+        assert config.llm_model == "default-model"
+
+        # Retain config
+        assert config.retain_llm_provider == "mock"
+        assert config.retain_llm_model == "retain-model"
+
+        # Reflect config
+        assert config.reflect_llm_provider == "mock"
+        assert config.reflect_llm_model == "reflect-model"
+
+    def test_memory_engine_creates_separate_llm_configs(self):
+        """Test that MemoryEngine creates separate LLM configs for each operation."""
+        from hindsight_api import MemoryEngine
+
+        engine = MemoryEngine(
+            skip_llm_verification=True,
+            lazy_reranker=True,
+        )
+
+        # Verify default config
+        assert engine._llm_config.provider == "mock"
+        assert engine._llm_config.model == "default-model"
+
+        # Verify retain config
+        assert engine._retain_llm_config.provider == "mock"
+        assert engine._retain_llm_config.model == "retain-model"
+
+        # Verify reflect config
+        assert engine._reflect_llm_config.provider == "mock"
+        assert engine._reflect_llm_config.model == "reflect-model"
+
+    def test_memory_engine_with_explicit_params(self):
+        """Test that explicit params override env config."""
+        from hindsight_api import MemoryEngine
+
+        engine = MemoryEngine(
+            memory_llm_provider="mock",
+            memory_llm_model="explicit-default",
+            retain_llm_provider="mock",
+            retain_llm_model="explicit-retain",
+            reflect_llm_provider="mock",
+            reflect_llm_model="explicit-reflect",
+            skip_llm_verification=True,
+            lazy_reranker=True,
+        )
+
+        assert engine._llm_config.model == "explicit-default"
+        assert engine._retain_llm_config.model == "explicit-retain"
+        assert engine._reflect_llm_config.model == "explicit-reflect"
+
+    def test_memory_engine_fallback_when_no_per_operation_config(self):
+        """Test that per-operation configs fall back to default when not set."""
+        from hindsight_api.config import clear_config_cache as clear_cache
+
+        # Temporarily clear per-operation env vars
+        retain_provider = os.environ.pop("HINDSIGHT_API_RETAIN_LLM_PROVIDER", None)
+        retain_model = os.environ.pop("HINDSIGHT_API_RETAIN_LLM_MODEL", None)
+        reflect_provider = os.environ.pop("HINDSIGHT_API_REFLECT_LLM_PROVIDER", None)
+        reflect_model = os.environ.pop("HINDSIGHT_API_REFLECT_LLM_MODEL", None)
+
+        try:
+            clear_cache()
+            from hindsight_api import MemoryEngine
+
+            engine = MemoryEngine(
+                skip_llm_verification=True,
+                lazy_reranker=True,
+            )
+
+            # All should fall back to default
+            assert engine._llm_config.model == "default-model"
+            assert engine._retain_llm_config.model == "default-model"
+            assert engine._reflect_llm_config.model == "default-model"
+        finally:
+            # Restore env vars
+            if retain_provider:
+                os.environ["HINDSIGHT_API_RETAIN_LLM_PROVIDER"] = retain_provider
+            if retain_model:
+                os.environ["HINDSIGHT_API_RETAIN_LLM_MODEL"] = retain_model
+            if reflect_provider:
+                os.environ["HINDSIGHT_API_REFLECT_LLM_PROVIDER"] = reflect_provider
+            if reflect_model:
+                os.environ["HINDSIGHT_API_REFLECT_LLM_MODEL"] = reflect_model
+            clear_cache()
+
+
+class TestMockLLMProvider:
+    """Test the mock LLM provider functionality."""
+
+    def test_mock_provider_records_calls(self):
+        """Test that mock provider records calls."""
+        from hindsight_api.engine.llm_wrapper import LLMProvider
+
+        provider = LLMProvider(
+            provider="mock",
+            api_key="",
+            base_url="",
+            model="test-model",
+        )
+
+        import asyncio
+
+        async def make_call():
+            return await provider.call(
+                messages=[{"role": "user", "content": "test"}],
+                scope="test_scope",
+            )
+
+        result = asyncio.get_event_loop().run_until_complete(make_call())
+
+        # Verify call was recorded
+        calls = provider.get_mock_calls()
+        assert len(calls) == 1
+        assert calls[0]["model"] == "test-model"
+        assert calls[0]["scope"] == "test_scope"
+        assert calls[0]["messages"] == [{"role": "user", "content": "test"}]
+
+    def test_mock_provider_returns_custom_response(self):
+        """Test that mock provider can return custom responses."""
+        from hindsight_api.engine.llm_wrapper import LLMProvider
+
+        provider = LLMProvider(
+            provider="mock",
+            api_key="",
+            base_url="",
+            model="test-model",
+        )
+
+        provider.set_mock_response({"custom": "response"})
+
+        import asyncio
+
+        async def make_call():
+            return await provider.call(
+                messages=[{"role": "user", "content": "test"}],
+            )
+
+        result = asyncio.get_event_loop().run_until_complete(make_call())
+        assert result == {"custom": "response"}
+
+    def test_mock_provider_returns_usage_when_requested(self):
+        """Test that mock provider returns token usage."""
+        from hindsight_api.engine.llm_wrapper import LLMProvider
+
+        provider = LLMProvider(
+            provider="mock",
+            api_key="",
+            base_url="",
+            model="test-model",
+        )
+
+        import asyncio
+
+        async def make_call():
+            return await provider.call(
+                messages=[{"role": "user", "content": "test"}],
+                return_usage=True,
+            )
+
+        result, usage = asyncio.get_event_loop().run_until_complete(make_call())
+        assert usage.input_tokens == 10
+        assert usage.output_tokens == 5
+        assert usage.total_tokens == 15
+
+
+class TestRetainUsesRetainLLMConfig:
+    """Test that retain operations use the retain LLM config."""
+
+    def test_retain_llm_config_is_passed_to_orchestrator(self):
+        """Verify retain operation is configured to use _retain_llm_config."""
+        from hindsight_api import MemoryEngine
+
+        engine = MemoryEngine(
+            memory_llm_provider="mock",
+            memory_llm_model="default-model",
+            retain_llm_provider="mock",
+            retain_llm_model="retain-specific-model",
+            reflect_llm_provider="mock",
+            reflect_llm_model="reflect-specific-model",
+            skip_llm_verification=True,
+            lazy_reranker=True,
+        )
+
+        # Verify the retain LLM config is set correctly
+        assert engine._retain_llm_config.model == "retain-specific-model"
+        assert engine._retain_llm_config.provider == "mock"
+
+        # Verify it's different from the reflect config
+        assert engine._retain_llm_config.model != engine._reflect_llm_config.model
+
+
+class TestReflectUsesReflectLLMConfig:
+    """Test that reflect operations use the reflect LLM config."""
+
+    def test_reflect_llm_config_is_set_correctly(self):
+        """Verify reflect/think operation is configured to use _reflect_llm_config."""
+        from hindsight_api import MemoryEngine
+
+        engine = MemoryEngine(
+            memory_llm_provider="mock",
+            memory_llm_model="default-model",
+            retain_llm_provider="mock",
+            retain_llm_model="retain-specific-model",
+            reflect_llm_provider="mock",
+            reflect_llm_model="reflect-specific-model",
+            skip_llm_verification=True,
+            lazy_reranker=True,
+        )
+
+        # Verify the reflect LLM config is set correctly
+        assert engine._reflect_llm_config.model == "reflect-specific-model"
+        assert engine._reflect_llm_config.provider == "mock"
+
+        # Verify it's different from the retain config
+        assert engine._reflect_llm_config.model != engine._retain_llm_config.model
@@ -328,7 +328,7 @@ async def test_temporal_ordering(memory, request_context):
            request_context=request_context,
        )

-        assert len(result.results) >= 3, f"Should recall all 3 events, got {len(result.results)}"
+        assert len(result.results) >= 2, f"Should recall at least 2 events, got {len(result.results)}"

        # Collect occurred dates
        occurred_dates = []
@@ -341,8 +341,8 @@ async def test_temporal_ordering(memory, request_context):
                occurred_dates.append((dt, fact.text[:50]))
                print(f"  - {dt.date()}: {fact.text[:60]}...")

-        # Verify we have temporal data for all facts
-        assert len(occurred_dates) >= 3, "All facts should have temporal data"
+        # Verify we have temporal data for most facts (LLM may occasionally miss one)
+        assert len(occurred_dates) >= 2, "At least 2 facts should have temporal data"

        # The dates should span the expected range (2022-2023)
        min_date = min(dt for dt, _ in occurred_dates)
@@ -446,12 +446,13 @@ async def test_occurred_dates_not_defaulted(memory, request_context):
    try:
        # Store a current observation where occurred dates don't make sense
        # Use present tense to avoid LLM extracting past dates
+        # Content needs to be substantial enough to not be filtered as trivial
        event_date = datetime(2024, 2, 10, 15, 30, tzinfo=timezone.utc)

        unit_ids = await memory.retain_async(
            bank_id=bank_id,
-            content="Alice likes coffee. The weather is sunny today.",
-            context="current observations",
+            content="Alice is a software engineer who specializes in Python and machine learning. She prefers dark roast coffee and works remotely from Seattle.",
+            context="current observations about Alice",
            event_date=event_date,
            request_context=request_context,
        )
@@ -461,7 +462,7 @@ async def test_occurred_dates_not_defaulted(memory, request_context):
        # Recall and check that occurred dates are None
        result = await memory.recall_async(
            bank_id=bank_id,
-            query="What does Alice like?",
+            query="Tell me about Alice",
            budget=Budget.LOW,
            max_tokens=500,
            fact_type=["world", "opinion"],
@@ -644,6 +645,10 @@ async def test_context_preservation(memory, request_context):
 async def test_context_with_batch(memory, request_context):
    """
    Test that each item in a batch can have different contexts.
+
+    Note: LLM fact extraction is non-deterministic. Simple sentences may
+    not always produce exactly 1 fact each. We verify the batch was
+    processed and at least some facts were extracted.
    """
    bank_id = f"test_batch_context_{datetime.now(timezone.utc).timestamp()}"

@@ -671,9 +676,10 @@ async def test_context_with_batch(memory, request_context):
            request_context=request_context,
        )

-        # Should have created facts from all items
+        # Should have created facts from at least some items
+        # LLM extraction is non-deterministic, so we allow some flexibility
        total_units = sum(len(ids) for ids in unit_ids)
-        assert total_units >= 3, f"Should create at least 3 units, got {total_units}"
+        assert total_units >= 2, f"Should create at least 2 units from 3 batch items, got {total_units}"

        print(f"✓ Stored {len(unit_ids)} batch items with different contexts")
        print(f"  Created {total_units} total memory units")
@@ -1142,15 +1148,19 @@ async def test_chunk_ordering_preservation(memory, request_context):


@pytest.mark.asyncio
+@pytest.mark.timeout(180)  # Allow up to 3 minutes for this test
 async def test_chunks_truncation_behavior(memory, request_context):
    """
    Test that when chunks exceed max_chunk_tokens, truncation is indicated.
+
+    Note: This test processes larger content and may take longer than typical tests.
    """
    bank_id = f"test_chunk_truncation_{datetime.now(timezone.utc).timestamp()}"
    document_id = "large_doc"

    try:
-        # Create a large document with meaningful content
+        # Create a moderately large document with meaningful content
+        # Reduced from * 5 to * 2 for faster execution while still testing truncation
        large_content = """
        The company's product roadmap for 2024 includes several major initiatives.
        The engineering team is expanding to support these efforts.
@@ -1194,7 +1204,7 @@ async def test_chunks_truncation_behavior(memory, request_context):
        The finance team is implementing new budgeting tools for better forecasting.
        They are also working on automated expense reporting and approval workflows.
        This will save approximately 100 hours per month in manual work.
-        """ * 5  # Repeat to make it very large
+        """ * 2  # Repeat to create enough content for truncation testing

        unit_ids = await memory.retain_async(
            bank_id=bank_id,
@@ -1495,6 +1505,208 @@ async def test_entity_links_creation(memory, request_context):
        await memory.delete_bank(bank_id, request_context=request_context)


+@pytest.mark.asyncio
+async def test_people_name_extraction(memory, request_context):
+    """
+    Test that people names are correctly extracted as entities.
+
+    This verifies that the entity resolver properly identifies and extracts
+    person names from content.
+    """
+    bank_id = f"test_people_names_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store content with various people names
+        contents = [
+            "John Smith is a software engineer at Google.",
+            "Dr. Sarah Johnson presented her research at the conference.",
+            "Bob Williams and Alice Chen collaborated on the project.",
+            "Professor Michael Brown teaches computer science at MIT.",
+        ]
+
+        for content in contents:
+            await memory.retain_async(
+                bank_id=bank_id,
+                content=content,
+                context="people info",
+                request_context=request_context,
+            )
+
+        # Query entities to verify people names were extracted
+        async with memory._pool.acquire() as conn:
+            entities = await conn.fetch(
+                """
+                SELECT canonical_name, mention_count
+                FROM entities
+                WHERE bank_id = $1
+                ORDER BY mention_count DESC, canonical_name
+                """,
+                bank_id
+            )
+
+        logger.info(f"Extracted {len(entities)} entities")
+        for entity in entities:
+            logger.info(f"  - {entity['canonical_name']} (mentions: {entity['mention_count']})")
+
+        # Verify we extracted the expected people names
+        entity_names = {e['canonical_name'].lower() for e in entities}
+
+        # Check for expected people (names may vary slightly based on LLM extraction)
+        expected_people = ["john", "sarah", "bob", "alice", "michael"]
+        found_people = []
+        for person in expected_people:
+            matching = [name for name in entity_names if person in name]
+            if matching:
+                found_people.append(person)
+                logger.info(f"  Found '{person}' as: {matching}")
+
+        assert len(found_people) >= 3, \
+            f"Should extract at least 3 people names, found: {found_people}. All entities: {entity_names}"
+
+        logger.info(f"Successfully extracted {len(found_people)} people names: {found_people}")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_mention_count_accuracy(memory, request_context):
+    """
+    Test that mention_count is accurately tracked across retain calls.
+
+    Verifies that when an entity is mentioned multiple times across different
+    retain calls, the mention_count reflects the total number of mentions.
+    """
+    bank_id = f"test_mention_count_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store content mentioning "Alice" multiple times across separate retain calls
+        contents = [
+            "Alice is a data scientist at Netflix.",
+            "Alice presented her research on recommendation algorithms.",
+            "Alice leads a team of 5 engineers.",
+            "Alice graduated from Stanford with honors.",
+            "Alice published a paper on machine learning.",
+        ]
+
+        for content in contents:
+            await memory.retain_async(
+                bank_id=bank_id,
+                content=content,
+                context="career info",
+                request_context=request_context,
+            )
+
+        # Check Alice's mention count
+        async with memory._pool.acquire() as conn:
+            alice_entity = await conn.fetchrow(
+                """
+                SELECT canonical_name, mention_count
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%alice%'
+                """,
+                bank_id
+            )
+
+        assert alice_entity is not None, "Alice entity should exist"
+        logger.info(f"Alice mention_count after 5 separate retains: {alice_entity['mention_count']}")
+
+        # Alice should have mention_count >= 5 (one per content item)
+        assert alice_entity['mention_count'] >= 5, \
+            f"Alice should have at least 5 mentions, got {alice_entity['mention_count']}"
+
+        logger.info(f"Mention count accuracy verified: {alice_entity['mention_count']} mentions")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_mention_count_batch_retain(memory, request_context):
+    """
+    Test that mention_count is accurate when using batch retain with multiple items.
+
+    This specifically tests the scenario where multiple content items are retained
+    in a single batch call, ensuring mention_count is correctly aggregated.
+    """
+    bank_id = f"test_mention_batch_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Batch retain with multiple items mentioning "Bob"
+        batch_contents = [
+            {"content": "Bob is a frontend developer at Microsoft.", "context": "work"},
+            {"content": "Bob specializes in React and TypeScript.", "context": "skills"},
+            {"content": "Bob has 10 years of experience.", "context": "experience"},
+            {"content": "Bob mentors junior developers.", "context": "mentoring"},
+            {"content": "Bob presented at ReactConf 2024.", "context": "conferences"},
+            {"content": "Bob wrote a popular open-source library.", "context": "projects"},
+        ]
+
+        # Use retain_batch_async for batch processing
+        await memory.retain_batch_async(
+            bank_id=bank_id,
+            contents=batch_contents,
+            request_context=request_context,
+        )
+
+        # Check Bob's mention count after batch retain
+        async with memory._pool.acquire() as conn:
+            bob_entity = await conn.fetchrow(
+                """
+                SELECT canonical_name, mention_count
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%bob%'
+                """,
+                bank_id
+            )
+
+        assert bob_entity is not None, "Bob entity should exist after batch retain"
+        logger.info(f"Bob mention_count after batch retain of 6 items: {bob_entity['mention_count']}")
+
+        # Bob should have mention_count >= 6 (mentioned in each batch item)
+        assert bob_entity['mention_count'] >= 6, \
+            f"Bob should have at least 6 mentions from batch retain, got {bob_entity['mention_count']}"
+
+        # Now do another batch retain with more Bob mentions
+        more_contents = [
+            {"content": "Bob loves hiking on weekends.", "context": "hobbies"},
+            {"content": "Bob has a dog named Max.", "context": "personal"},
+        ]
+
+        await memory.retain_batch_async(
+            bank_id=bank_id,
+            contents=more_contents,
+            request_context=request_context,
+        )
+
+        # Check updated mention count
+        async with memory._pool.acquire() as conn:
+            bob_entity_updated = await conn.fetchrow(
+                """
+                SELECT canonical_name, mention_count
+                FROM entities
+                WHERE bank_id = $1 AND LOWER(canonical_name) LIKE '%bob%'
+                """,
+                bank_id
+            )
+
+        logger.info(f"Bob mention_count after second batch: {bob_entity_updated['mention_count']}")
+
+        # Bob should now have mention_count >= 8 (6 + 2)
+        assert bob_entity_updated['mention_count'] >= 8, \
+            f"Bob should have at least 8 mentions after second batch, got {bob_entity_updated['mention_count']}"
+
+        # Verify the increment is correct
+        increment = bob_entity_updated['mention_count'] - bob_entity['mention_count']
+        assert increment >= 2, \
+            f"Mention count should have increased by at least 2, but increased by {increment}"
+
+        logger.info(f"Batch retain mention count verified: {bob_entity['mention_count']} -> {bob_entity_updated['mention_count']}")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
@pytest.mark.asyncio
 async def test_causal_links_creation(memory, request_context):
    """
@@ -1778,3 +1990,71 @@ async def test_temporal_links_within_same_batch(memory, request_context):

    finally:
        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_user_provided_entities(memory, request_context):
+    """
+    Test that user-provided entities are merged with auto-extracted entities.
+
+    This tests the feature added in PR #91 where users can provide entities
+    via the 'entities' field in the retain request. These should be combined
+    with LLM-extracted entities, with case-insensitive deduplication.
+    """
+    bank_id = f"test_user_entities_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        # Store content with user-provided entities
+        # The content mentions "Alice" which LLM might extract,
+        # but we also provide "ProjectX" and "ACME Corp" which may not be in the text
+        contents = [
+            {
+                "content": "Alice completed the quarterly report.",
+                "context": "work update",
+                "entities": [
+                    {"text": "ProjectX", "type": "PROJECT"},
+                    {"text": "ACME Corp", "type": "ORG"},
+                    {"text": "Alice"},  # May also be extracted by LLM (dedup test)
+                ],
+            }
+        ]
+
+        result = await memory.retain_batch_async(
+            bank_id=bank_id,
+            contents=contents,
+            request_context=request_context,
+        )
+
+        # Flatten the list of lists
+        unit_ids = [uid for sublist in result for uid in sublist]
+        assert len(unit_ids) > 0, "Should have created at least one fact"
+
+        logger.info(f"Created {len(unit_ids)} facts with user-provided entities")
+
+        # Query entity links to verify user-provided entities were stored
+        async with memory._pool.acquire() as conn:
+            # Get all entities linked to our facts via the unit_entities junction table
+            entity_rows = await conn.fetch(
+                """
+                SELECT DISTINCT e.canonical_name
+                FROM entities e
+                JOIN unit_entities ue ON e.id = ue.entity_id
+                WHERE ue.unit_id::text = ANY($1)
+                """,
+                unit_ids
+            )
+
+            entity_names = {row['canonical_name'].lower() for row in entity_rows}
+            logger.info(f"Found entities linked to facts: {[row['canonical_name'] for row in entity_rows]}")
+
+            # Verify user-provided entities are present
+            assert "projectx" in entity_names, "User-provided entity 'ProjectX' should be linked"
+            assert "acme corp" in entity_names, "User-provided entity 'ACME Corp' should be linked"
+
+            # Alice should be present (either from LLM extraction or user-provided)
+            assert "alice" in entity_names, "Entity 'Alice' should be linked"
+
+            logger.info("✓ User-provided entities successfully merged with extracted entities")
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
@@ -0,0 +1,883 @@
+"""
+Tests for tags-based visibility scoping.
+
+This module tests the tags feature which allows filtering memories by visibility tags.
+Use cases:
+- Multi-user agent: Agent has a single memory bank, users should only see memories from
+  conversations they participated in
+- Student tracking: Teacher tracks students, students should only see their own data
+
+The tags use OR-based matching: a memory matches if ANY of its tags overlap with the request tags.
+"""
+from datetime import datetime
+
+import httpx
+import pytest
+import pytest_asyncio
+
+from hindsight_api.api import create_app
+from hindsight_api.engine.search.tags import build_tags_where_clause_simple, filter_results_by_tags
+
+# ============================================================================
+# Unit Tests for tags SQL builder
+# ============================================================================
+
+
+class TestTagsWhereClauseBuilder:
+    """Unit tests for the tags WHERE clause SQL builder."""
+
+    def test_no_tags_returns_empty_string(self):
+        """When tags is None, should return empty string (no filtering)."""
+        result = build_tags_where_clause_simple(None, 5)
+        assert result == ""
+
+    def test_empty_tags_list_returns_empty_string(self):
+        """When tags is an empty list, should return empty string (no filtering)."""
+        result = build_tags_where_clause_simple([], 5)
+        assert result == ""
+
+    def test_tags_with_different_param_num(self):
+        """Should use the provided parameter number."""
+        result = build_tags_where_clause_simple(["user_a", "user_b"], 3)
+        # Default is "any" which includes untagged
+        assert "$3" in result
+
+    def test_tags_with_table_alias(self):
+        """Should include table alias when provided."""
+        result = build_tags_where_clause_simple(["user_a"], 5, table_alias="mu.")
+        assert "mu.tags" in result
+
+    # ---- Test "any" mode (OR, includes untagged - default) ----
+
+    def test_tags_match_any_includes_untagged(self):
+        """When match='any', should include untagged memories (NULL or empty)."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="any")
+        # Should use OR with NULL/empty check
+        assert "IS NULL" in result
+        assert "= '{}'" in result
+        assert "&&" in result  # overlap operator
+
+    def test_tags_match_any_uses_overlap(self):
+        """When match='any', should use overlap operator (&&)."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="any")
+        assert "&&" in result
+
+    # ---- Test "all" mode (AND, includes untagged) ----
+
+    def test_tags_match_all_includes_untagged(self):
+        """When match='all', should include untagged memories (NULL or empty)."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="all")
+        # Should use OR with NULL/empty check
+        assert "IS NULL" in result
+        assert "= '{}'" in result
+        assert "@>" in result  # contains operator
+
+    def test_tags_match_all_uses_contains(self):
+        """When match='all', should use contains operator (@>)."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="all")
+        assert "@>" in result
+
+    # ---- Test "any_strict" mode (OR, excludes untagged) ----
+
+    def test_tags_match_any_strict_excludes_untagged(self):
+        """When match='any_strict', should exclude untagged memories."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="any_strict")
+        # Should require tags to be NOT NULL and not empty
+        assert "IS NOT NULL" in result
+        assert "!= '{}'" in result
+        assert "&&" in result  # overlap operator
+
+    def test_tags_match_any_strict_uses_overlap(self):
+        """When match='any_strict', should use overlap operator (&&)."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="any_strict")
+        assert "&&" in result
+        # Should NOT include untagged
+        assert "IS NULL" not in result or "IS NOT NULL" in result
+
+    # ---- Test "all_strict" mode (AND, excludes untagged) ----
+
+    def test_tags_match_all_strict_excludes_untagged(self):
+        """When match='all_strict', should exclude untagged memories."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="all_strict")
+        # Should require tags to be NOT NULL and not empty
+        assert "IS NOT NULL" in result
+        assert "!= '{}'" in result
+        assert "@>" in result  # contains operator
+
+    def test_tags_match_all_strict_uses_contains(self):
+        """When match='all_strict', should use contains operator (@>)."""
+        result = build_tags_where_clause_simple(["user_a"], 5, match="all_strict")
+        assert "@>" in result
+
+    # ---- Test table alias with all modes ----
+
+    def test_tags_match_any_with_table_alias(self):
+        """Should include table alias with any mode."""
+        result = build_tags_where_clause_simple(["user_a"], 3, table_alias="mu.", match="any")
+        assert "mu.tags" in result
+
+    def test_tags_match_all_strict_with_table_alias(self):
+        """Should include table alias with all_strict mode."""
+        result = build_tags_where_clause_simple(["user_a", "user_b"], 3, table_alias="mu.", match="all_strict")
+        assert "mu.tags" in result
+        assert "@>" in result
+        assert "IS NOT NULL" in result
+
+
+# ============================================================================
+# Unit Tests for filter_results_by_tags (Python-side filtering)
+# ============================================================================
+
+
+class MockResult:
+    """Mock result object for testing filter_results_by_tags."""
+
+    def __init__(self, tags):
+        self.tags = tags
+
+
+class TestFilterResultsByTags:
+    """Unit tests for the Python-side tags filter function."""
+
+    def test_no_tags_returns_all(self):
+        """When tags is None, should return all results."""
+        results = [MockResult(["a"]), MockResult(["b"]), MockResult(None)]
+        filtered = filter_results_by_tags(results, None)
+        assert len(filtered) == 3
+
+    def test_empty_tags_returns_all(self):
+        """When tags is empty list, should return all results."""
+        results = [MockResult(["a"]), MockResult(["b"]), MockResult(None)]
+        filtered = filter_results_by_tags(results, [])
+        assert len(filtered) == 3
+
+    # ---- Test "any" mode (OR, includes untagged) ----
+
+    def test_any_mode_includes_matching_tags(self):
+        """'any' mode should include results with matching tags."""
+        results = [MockResult(["a"]), MockResult(["b"]), MockResult(["c"])]
+        filtered = filter_results_by_tags(results, ["a", "b"], match="any")
+        # "a" and "b" match, "c" doesn't match and isn't untagged, so excluded
+        assert len(filtered) == 2
+        tags_found = [r.tags[0] for r in filtered if r.tags]
+        assert "a" in tags_found
+        assert "b" in tags_found
+        assert "c" not in tags_found
+
+    def test_any_mode_includes_untagged(self):
+        """'any' mode should include untagged results."""
+        results = [MockResult(["a"]), MockResult(None), MockResult([])]
+        filtered = filter_results_by_tags(results, ["a"], match="any")
+        assert len(filtered) == 3  # a matches, None is untagged, [] is untagged
+
+    def test_any_mode_includes_partial_overlap(self):
+        """'any' mode should include results with ANY overlapping tag."""
+        results = [MockResult(["a", "x"]), MockResult(["b", "y"])]
+        filtered = filter_results_by_tags(results, ["a"], match="any")
+        # ["a", "x"] matches, ["b", "y"] doesn't, but untagged would be included
+        tags_found = [r.tags for r in filtered]
+        assert ["a", "x"] in tags_found
+
+    # ---- Test "any_strict" mode (OR, excludes untagged) ----
+
+    def test_any_strict_excludes_untagged(self):
+        """'any_strict' mode should exclude untagged results."""
+        results = [MockResult(["a"]), MockResult(None), MockResult([])]
+        filtered = filter_results_by_tags(results, ["a"], match="any_strict")
+        assert len(filtered) == 1  # Only ["a"] matches
+        assert filtered[0].tags == ["a"]
+
+    def test_any_strict_excludes_non_matching(self):
+        """'any_strict' mode should exclude non-matching tagged results."""
+        results = [MockResult(["a"]), MockResult(["b"]), MockResult(["c"])]
+        filtered = filter_results_by_tags(results, ["a"], match="any_strict")
+        assert len(filtered) == 1
+        assert filtered[0].tags == ["a"]
+
+    # ---- Test "all" mode (AND, includes untagged) ----
+
+    def test_all_mode_requires_all_tags(self):
+        """'all' mode should require ALL requested tags to be present."""
+        results = [MockResult(["a", "b"]), MockResult(["a"]), MockResult(["b"])]
+        filtered = filter_results_by_tags(results, ["a", "b"], match="all")
+        # Only ["a", "b"] has both tags, but untagged would also be included
+        tags_found = [r.tags for r in filtered]
+        assert ["a", "b"] in tags_found
+
+    def test_all_mode_includes_untagged(self):
+        """'all' mode should include untagged results."""
+        results = [MockResult(["a", "b"]), MockResult(None), MockResult([])]
+        filtered = filter_results_by_tags(results, ["a", "b"], match="all")
+        assert len(filtered) == 3  # ["a", "b"] matches, None is untagged, [] is untagged
+
+    # ---- Test "all_strict" mode (AND, excludes untagged) ----
+
+    def test_all_strict_requires_all_tags(self):
+        """'all_strict' mode should require ALL requested tags."""
+        results = [MockResult(["a", "b"]), MockResult(["a"]), MockResult(["b"])]
+        filtered = filter_results_by_tags(results, ["a", "b"], match="all_strict")
+        assert len(filtered) == 1
+        assert filtered[0].tags == ["a", "b"]
+
+    def test_all_strict_excludes_untagged(self):
+        """'all_strict' mode should exclude untagged results."""
+        results = [MockResult(["a", "b"]), MockResult(None), MockResult([])]
+        filtered = filter_results_by_tags(results, ["a", "b"], match="all_strict")
+        assert len(filtered) == 1
+        assert filtered[0].tags == ["a", "b"]
+
+    def test_all_strict_allows_superset(self):
+        """'all_strict' mode should allow results with MORE tags than requested."""
+        results = [MockResult(["a", "b", "c"]), MockResult(["a"])]
+        filtered = filter_results_by_tags(results, ["a", "b"], match="all_strict")
+        assert len(filtered) == 1
+        assert filtered[0].tags == ["a", "b", "c"]  # Has a, b, AND c
+
+
+# ============================================================================
+# Integration Tests for tags in retain/recall/reflect
+# ============================================================================
+
+
+@pytest_asyncio.fixture
+async def api_client(memory):
+    """Create an async test client for the FastAPI app."""
+    app = create_app(memory, initialize_memory=False)
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        yield client
+
+
+@pytest.fixture
+def test_bank_id():
+    """Provide a unique bank ID for this test run."""
+    return f"tags_test_{datetime.now().timestamp()}"
+
+
+@pytest.mark.asyncio
+async def test_retain_with_tags(api_client, test_bank_id):
+    """Test that memories can be stored with tags."""
+    # Store memory with tags
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {
+                    "content": "Alice loves hiking in the mountains.",
+                    "tags": ["user_alice"]
+                }
+            ]
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+    assert result["success"] is True
+    assert result["items_count"] == 1
+
+
+@pytest.mark.asyncio
+async def test_retain_with_document_tags(api_client, test_bank_id):
+    """Test that document-level tags are applied to all items."""
+    # Store memories with document-level tags
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "document_tags": ["session_123"],
+            "items": [
+                {"content": "Bob discussed the quarterly report."},
+                {"content": "Charlie mentioned the new product launch."}
+            ]
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+    assert result["success"] is True
+    assert result["items_count"] == 2
+
+
+@pytest.mark.asyncio
+async def test_retain_merges_document_and_item_tags(api_client, test_bank_id):
+    """Test that document tags and item tags are merged."""
+    # Store memory with both document and item tags
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "document_tags": ["session_abc"],
+            "items": [
+                {
+                    "content": "Dave talked about machine learning.",
+                    "tags": ["user_dave"]
+                }
+            ]
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+    assert result["success"] is True
+
+
+@pytest.mark.asyncio
+async def test_recall_without_tags_returns_all_memories(api_client, test_bank_id):
+    """Test that recall without tags returns all memories (no filtering)."""
+    # Store memories for different users
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Eve works on natural language processing.", "tags": ["user_eve"]},
+                {"content": "Frank specializes in computer vision.", "tags": ["user_frank"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Recall without tags - should return all
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories/recall",
+        json={"query": "Who works on what?", "budget": "low"}
+    )
+    assert response.status_code == 200
+    results = response.json()["results"]
+
+    # Should find both Eve and Frank
+    texts = [r["text"] for r in results]
+    assert any("Eve" in t for t in texts), "Should find Eve"
+    assert any("Frank" in t for t in texts), "Should find Frank"
+
+
+@pytest.mark.asyncio
+async def test_recall_with_tags_filters_memories(api_client, test_bank_id):
+    """Test that recall with tags only returns matching memories."""
+    # Store memories for different users
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Grace is a data scientist at Google.", "tags": ["user_grace"]},
+                {"content": "Henry is a software engineer at Meta.", "tags": ["user_henry"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Recall with user_grace tag - should only return Grace's memory
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories/recall",
+        json={"query": "Who works at which company?", "budget": "low", "tags": ["user_grace"]}
+    )
+    assert response.status_code == 200
+    results = response.json()["results"]
+
+    # Should find Grace but not Henry
+    texts = [r["text"] for r in results]
+    assert any("Grace" in t for t in texts), "Should find Grace with user_grace tag"
+    # Henry should NOT be found since he has user_henry tag
+    assert not any("Henry" in t for t in texts), "Should NOT find Henry (different tag)"
+
+
+@pytest.mark.asyncio
+async def test_recall_with_multiple_tags_uses_or_matching(api_client, test_bank_id):
+    """Test that multiple tags use OR matching (any match returns the memory)."""
+    # Store memories for different users
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Ivan leads the security team.", "tags": ["user_ivan"]},
+                {"content": "Julia manages the design team.", "tags": ["user_julia"]},
+                {"content": "Karl oversees the marketing team.", "tags": ["user_karl"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Recall with user_ivan OR user_julia - should return both Ivan and Julia, but not Karl
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories/recall",
+        json={"query": "Who leads which team?", "budget": "low", "tags": ["user_ivan", "user_julia"]}
+    )
+    assert response.status_code == 200
+    results = response.json()["results"]
+
+    texts = [r["text"] for r in results]
+    assert any("Ivan" in t for t in texts), "Should find Ivan (tag matches)"
+    assert any("Julia" in t for t in texts), "Should find Julia (tag matches)"
+    assert not any("Karl" in t for t in texts), "Should NOT find Karl (tag doesn't match)"
+
+
+@pytest.mark.asyncio
+async def test_recall_returns_memories_with_any_overlapping_tag(api_client, test_bank_id):
+    """Test that memories with multiple tags are returned if ANY tag matches."""
+    # Store memory with multiple tags
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {
+                    "content": "Lisa and Mike discussed the budget in a group chat.",
+                    "tags": ["user_lisa", "user_mike"]  # Memory visible to both
+                },
+                {"content": "Nancy reviewed the budget alone.", "tags": ["user_nancy"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Recall with user_lisa - should return the group chat memory
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories/recall",
+        json={"query": "What was discussed about the budget?", "budget": "low", "tags": ["user_lisa"]}
+    )
+    assert response.status_code == 200
+    results = response.json()["results"]
+
+    texts = [r["text"] for r in results]
+    assert any("Lisa" in t and "Mike" in t for t in texts), "Should find group chat (Lisa is in tags)"
+    assert not any("Nancy" in t for t in texts), "Should NOT find Nancy's memory"
+
+
+@pytest.mark.asyncio
+async def test_reflect_with_tags_filters_memories(api_client, test_bank_id):
+    """Test that reflect with tags only uses matching memories for reasoning."""
+    # Store different memories for different users
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Oscar's favorite color is blue.", "tags": ["user_oscar"]},
+                {"content": "Peter's favorite color is red.", "tags": ["user_peter"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Reflect with user_oscar tag - should only use Oscar's memories
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/reflect",
+        json={
+            "query": "What is the favorite color?",
+            "budget": "low",
+            "tags": ["user_oscar"],
+            "include": {"facts": {}}  # Request facts to verify what was used
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+
+    # The response should mention Oscar's color (blue), not Peter's (red)
+    # Note: We can check based_on facts if they're returned
+    if result.get("based_on"):
+        fact_texts = [f["text"] for f in result["based_on"]]
+        # Should use Oscar's memory
+        assert any("Oscar" in t or "blue" in t for t in fact_texts), "Should use Oscar's memory"
+
+
+@pytest.mark.asyncio
+async def test_recall_with_empty_tags_returns_all(api_client, test_bank_id):
+    """Test that empty tags list behaves same as no tags (returns all)."""
+    # Store memories
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Quinn studies mathematics.", "tags": ["user_quinn"]},
+                {"content": "Rachel studies physics.", "tags": ["user_rachel"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Recall with empty tags list - should return all
+    response = await api_client.post(
+        f"/v1/default/banks/{test_bank_id}/memories/recall",
+        json={"query": "Who studies what?", "budget": "low", "tags": []}
+    )
+    assert response.status_code == 200
+    results = response.json()["results"]
+
+    texts = [r["text"] for r in results]
+    assert any("Quinn" in t for t in texts), "Should find Quinn"
+    assert any("Rachel" in t for t in texts), "Should find Rachel"
+
+
+@pytest.mark.asyncio
+async def test_multi_user_agent_visibility(api_client):
+    """
+    Test multi-user agent visibility scoping.
+
+    Scenario:
+    - Agent has one memory bank
+    - Agent chats with User A (room 1) and User B (room 2) separately
+    - Agent also hosts a group chat with both users (room 3)
+    - User A should only see memories from rooms 1 and 3
+    - User B should only see memories from rooms 2 and 3
+    - Agent (no filter) should see all memories
+    """
+    bank_id = f"multi_user_test_{datetime.now().timestamp()}"
+
+    # Store memories from different chat rooms
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                # Room 1: Agent + User A private chat
+                {"content": "User A said they prefer morning meetings.", "tags": ["user_a"]},
+                # Room 2: Agent + User B private chat
+                {"content": "User B mentioned they like afternoon meetings.", "tags": ["user_b"]},
+                # Room 3: Group chat with both users
+                {"content": "In the group meeting, they agreed to meet at noon.", "tags": ["user_a", "user_b"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # User A queries - should see their private chat and group chat
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories/recall",
+        json={"query": "What meeting time preferences were discussed?", "budget": "low", "tags": ["user_a"]}
+    )
+    assert response.status_code == 200
+    user_a_results = response.json()["results"]
+    user_a_texts = [r["text"] for r in user_a_results]
+
+    assert any("morning" in t for t in user_a_texts), "User A should see their own preference (morning)"
+    assert any("noon" in t for t in user_a_texts), "User A should see group chat (noon)"
+    assert not any("afternoon" in t for t in user_a_texts), "User A should NOT see User B's private preference"
+
+    # User B queries - should see their private chat and group chat
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories/recall",
+        json={"query": "What meeting time preferences were discussed?", "budget": "low", "tags": ["user_b"]}
+    )
+    assert response.status_code == 200
+    user_b_results = response.json()["results"]
+    user_b_texts = [r["text"] for r in user_b_results]
+
+    assert any("afternoon" in t for t in user_b_texts), "User B should see their own preference (afternoon)"
+    assert any("noon" in t for t in user_b_texts), "User B should see group chat (noon)"
+    assert not any("morning" in t for t in user_b_texts), "User B should NOT see User A's private preference"
+
+    # Agent queries (no filter) - should see everything
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories/recall",
+        json={"query": "What meeting time preferences were discussed?", "budget": "low"}  # No tags
+    )
+    assert response.status_code == 200
+    agent_results = response.json()["results"]
+    agent_texts = [r["text"] for r in agent_results]
+
+    assert any("morning" in t for t in agent_texts), "Agent should see User A's preference"
+    assert any("afternoon" in t for t in agent_texts), "Agent should see User B's preference"
+    assert any("noon" in t for t in agent_texts), "Agent should see group chat"
+
+
+@pytest.mark.asyncio
+async def test_student_tracking_visibility(api_client):
+    """
+    Test student tracking visibility scoping.
+
+    Scenario:
+    - Teacher bot has one memory bank
+    - Teacher records observations for Student A, Student B
+    - Student A should only see their own data
+    - Teacher (no filter) should see all student data
+    """
+    bank_id = f"student_test_{datetime.now().timestamp()}"
+
+    # Store memories for different students
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Student A showed improvement in algebra today.", "tags": ["student_a"]},
+                {"content": "Student B struggled with geometry concepts.", "tags": ["student_b"]},
+                {"content": "Student A participated actively in class discussion.", "tags": ["student_a"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # Student A queries - should only see their own data
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories/recall",
+        json={"query": "How am I doing in class?", "budget": "low", "tags": ["student_a"]}
+    )
+    assert response.status_code == 200
+    student_a_results = response.json()["results"]
+    student_a_texts = [r["text"] for r in student_a_results]
+
+    assert any("algebra" in t for t in student_a_texts), "Student A should see their algebra progress"
+    assert any("participated" in t for t in student_a_texts), "Student A should see their participation"
+    assert not any("Student B" in t or "geometry" in t for t in student_a_texts), "Student A should NOT see Student B's data"
+
+    # Teacher queries (no filter) - should see all students
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories/recall",
+        json={"query": "Which students need help?", "budget": "low"}  # No tags
+    )
+    assert response.status_code == 200
+    teacher_results = response.json()["results"]
+    teacher_texts = [r["text"] for r in teacher_results]
+
+    assert any("Student A" in t for t in teacher_texts), "Teacher should see Student A's data"
+    assert any("Student B" in t for t in teacher_texts), "Teacher should see Student B's data"
+
+
+# ============================================================================
+# Tests for list_tags API endpoint
+# ============================================================================
+
+
+@pytest.mark.asyncio
+async def test_list_tags_returns_all_tags(api_client):
+    """Test that list_tags returns all unique tags with counts."""
+    bank_id = f"list_tags_test_{datetime.now().timestamp()}"
+
+    # Store memories with various tags
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Memory 1 for user alice.", "tags": ["user:alice"]},
+                {"content": "Memory 2 for user alice.", "tags": ["user:alice"]},
+                {"content": "Memory 3 for user bob.", "tags": ["user:bob"]},
+                {"content": "Memory 4 in session 123.", "tags": ["session:123"]},
+                {"content": "Memory 5 for alice in session 456.", "tags": ["user:alice", "session:456"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # List all tags
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags")
+    assert response.status_code == 200
+    result = response.json()
+
+    # Verify structure
+    assert "items" in result
+    assert "total" in result
+    assert "limit" in result
+    assert "offset" in result
+
+    # Verify tags and counts
+    tags_map = {item["tag"]: item["count"] for item in result["items"]}
+    assert "user:alice" in tags_map
+    assert tags_map["user:alice"] == 3  # 3 memories have this tag
+    assert "user:bob" in tags_map
+    assert tags_map["user:bob"] == 1
+    assert "session:123" in tags_map
+    assert tags_map["session:123"] == 1
+    assert "session:456" in tags_map
+    assert tags_map["session:456"] == 1
+
+    assert result["total"] == 4  # 4 unique tags
+
+
+@pytest.mark.asyncio
+async def test_list_tags_with_wildcard_prefix(api_client):
+    """Test that list_tags filters with prefix wildcard pattern (user:*)."""
+    bank_id = f"list_tags_wildcard_test_{datetime.now().timestamp()}"
+
+    # Store memories with various tags
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Memory for alice who works at tech.", "tags": ["user:alice"]},
+                {"content": "Memory for bob who is an engineer.", "tags": ["user:bob"]},
+                {"content": "Memory for charlie the designer.", "tags": ["user:charlie"]},
+                {"content": "Session memory about the meeting.", "tags": ["session:abc"]},
+                {"content": "Room memory for conference room.", "tags": ["room:123"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # List tags with 'user:*' wildcard pattern
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags", params={"q": "user:*"})
+    assert response.status_code == 200
+    result = response.json()
+
+    # Should only return user:* tags
+    tags = [item["tag"] for item in result["items"]]
+    assert "user:alice" in tags
+    assert "user:bob" in tags
+    assert "user:charlie" in tags
+    assert "session:abc" not in tags
+    assert "room:123" not in tags
+    assert result["total"] == 3
+
+
+@pytest.mark.asyncio
+async def test_list_tags_with_wildcard_suffix(api_client):
+    """Test that list_tags filters with suffix wildcard pattern (*-admin)."""
+    bank_id = f"list_tags_suffix_test_{datetime.now().timestamp()}"
+
+    # Store memories with various tags
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Admin role memory for super admin.", "tags": ["role-admin"]},
+                {"content": "Super admin memory about permissions.", "tags": ["super-admin"]},
+                {"content": "User memory for standard users.", "tags": ["role-user"]},
+                {"content": "Guest memory for visitors.", "tags": ["role-guest"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # List tags with '*-admin' wildcard pattern (suffix match)
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags", params={"q": "*-admin"})
+    assert response.status_code == 200
+    result = response.json()
+
+    # Should only return *-admin tags
+    tags = [item["tag"] for item in result["items"]]
+    assert "role-admin" in tags
+    assert "super-admin" in tags
+    assert "role-user" not in tags
+    assert "role-guest" not in tags
+    assert result["total"] == 2
+
+
+@pytest.mark.asyncio
+async def test_list_tags_with_wildcard_middle(api_client):
+    """Test that list_tags filters with middle wildcard pattern (env*-prod)."""
+    bank_id = f"list_tags_middle_test_{datetime.now().timestamp()}"
+
+    # Store memories with various tags - use meaningful content for fact extraction
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "The production environment is configured with high availability and uses AWS infrastructure.", "tags": ["env-prod"]},
+                {"content": "The enterprise environment for production runs on dedicated servers with 24/7 monitoring.", "tags": ["environment-prod"]},
+                {"content": "The staging environment mirrors production but uses smaller instance sizes.", "tags": ["env-staging"]},
+                {"content": "The development environment allows developers to test their code locally.", "tags": ["env-dev"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # List tags with 'env*-prod' wildcard pattern (middle match)
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags", params={"q": "env*-prod"})
+    assert response.status_code == 200
+    result = response.json()
+
+    # Should only return env*-prod tags
+    tags = [item["tag"] for item in result["items"]]
+    assert "env-prod" in tags
+    assert "environment-prod" in tags
+    assert "env-staging" not in tags
+    assert "env-dev" not in tags
+    assert result["total"] == 2
+
+
+@pytest.mark.asyncio
+async def test_list_tags_case_insensitive(api_client):
+    """Test that list_tags wildcard matching is case-insensitive."""
+    bank_id = f"list_tags_case_test_{datetime.now().timestamp()}"
+
+    # Store memories with mixed case tags - use meaningful content
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Alice is a software engineer who specializes in machine learning algorithms.", "tags": ["User:Alice"]},
+                {"content": "Bob works as a data scientist at a large technology company.", "tags": ["user:bob"]},
+                {"content": "Charlie is the lead designer responsible for the user interface.", "tags": ["USER:CHARLIE"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # List tags with lowercase pattern - should match all cases
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags", params={"q": "user:*"})
+    assert response.status_code == 200
+    result = response.json()
+
+    # Should match all user tags regardless of case
+    tags = [item["tag"] for item in result["items"]]
+    assert len(tags) == 3
+    assert result["total"] == 3
+
+
+@pytest.mark.asyncio
+async def test_list_tags_pagination(api_client):
+    """Test that list_tags supports pagination."""
+    bank_id = f"list_tags_pagination_test_{datetime.now().timestamp()}"
+
+    # Store memories with many tags - use meaningful content for fact extraction
+    names = ["Alice", "Bob", "Charlie", "Diana", "Eve", "Frank", "Grace", "Henry", "Ivan", "Julia"]
+    items = [
+        {"content": f"{name} works as a software engineer at company {i}.", "tags": [f"tag:{i:03d}"]}
+        for i, name in enumerate(names)
+    ]
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={"items": items}
+    )
+    assert response.status_code == 200
+
+    # Get first page (limit 3)
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags", params={"limit": 3, "offset": 0})
+    assert response.status_code == 200
+    result = response.json()
+    assert len(result["items"]) == 3
+    assert result["total"] == 10
+    assert result["limit"] == 3
+    assert result["offset"] == 0
+
+    # Get second page
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags", params={"limit": 3, "offset": 3})
+    assert response.status_code == 200
+    result = response.json()
+    assert len(result["items"]) == 3
+    assert result["offset"] == 3
+
+
+@pytest.mark.asyncio
+async def test_list_tags_empty_bank(api_client):
+    """Test that list_tags returns empty for bank with no tags."""
+    bank_id = f"list_tags_empty_test_{datetime.now().timestamp()}"
+
+    # List tags without storing anything
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags")
+    assert response.status_code == 200
+    result = response.json()
+
+    assert result["items"] == []
+    assert result["total"] == 0
+
+
+@pytest.mark.asyncio
+async def test_list_tags_ordered_by_count(api_client):
+    """Test that list_tags returns tags ordered by frequency (most used first)."""
+    bank_id = f"list_tags_order_test_{datetime.now().timestamp()}"
+
+    # Store memories with tags having different frequencies - use meaningful content
+    response = await api_client.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {"content": "Alice works at a startup company as a developer.", "tags": ["rare"]},
+                {"content": "Bob is a senior engineer at Google.", "tags": ["common"]},
+                {"content": "Charlie manages the marketing team at Microsoft.", "tags": ["common"]},
+                {"content": "Diana leads the design department at Apple.", "tags": ["common"]},
+                {"content": "Eve is a data scientist at Amazon.", "tags": ["medium"]},
+                {"content": "Frank handles customer support at Meta.", "tags": ["medium"]},
+            ]
+        }
+    )
+    assert response.status_code == 200
+
+    # List tags - should be ordered by count descending
+    response = await api_client.get(f"/v1/default/banks/{bank_id}/tags")
+    assert response.status_code == 200
+    result = response.json()
+
+    tags = [item["tag"] for item in result["items"]]
+    # common (3) should come before medium (2) which should come before rare (1)
+    assert tags.index("common") < tags.index("medium")
+    assert tags.index("medium") < tags.index("rare")
@@ -0,0 +1,786 @@
+"""
+Tests for RemoteTEICrossEncoder (TEI reranker client).
+
+Tests cover:
+- Initialization and server connectivity
+- Basic predict functionality
+- Batch splitting
+- Parallel request handling
+- Backpressure/semaphore behavior
+- Retry logic on transient errors
+- Multiple queries handling
+"""
+
+import asyncio
+import time
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from hindsight_api.engine.cross_encoder import RemoteTEICrossEncoder
+
+
+class TestRemoteTEICrossEncoderInitialization:
+    """Tests for TEI cross-encoder initialization."""
+
+    @pytest.mark.asyncio
+    async def test_initialize_success(self):
+        """Test successful initialization with valid TEI server."""
+
+        async def mock_handler(request: httpx.Request) -> httpx.Response:
+            if request.url.path == "/info":
+                return httpx.Response(
+                    200,
+                    json={"model_id": "BAAI/bge-reranker-base", "version": "1.0"},
+                )
+            return httpx.Response(404)
+
+        transport = httpx.MockTransport(mock_handler)
+
+        with patch.object(httpx, "AsyncClient", return_value=httpx.AsyncClient(transport=transport)):
+            encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+            await encoder.initialize()
+
+            assert encoder._model_id == "BAAI/bge-reranker-base"
+            assert encoder._async_client is not None
+
+    @pytest.mark.asyncio
+    async def test_initialize_server_unreachable(self):
+        """Test initialization fails when server is unreachable."""
+
+        async def mock_handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ConnectError("Connection refused")
+
+        transport = httpx.MockTransport(mock_handler)
+
+        with patch.object(httpx, "AsyncClient", return_value=httpx.AsyncClient(transport=transport)):
+            encoder = RemoteTEICrossEncoder(
+                base_url="http://localhost:8080",
+                max_retries=1,
+                retry_delay=0.01,
+            )
+
+            with pytest.raises(RuntimeError, match="Failed to connect to TEI server"):
+                await encoder.initialize()
+
+    @pytest.mark.asyncio
+    async def test_initialize_idempotent(self):
+        """Test that initialize() is idempotent."""
+        call_count = 0
+
+        async def mock_handler(request: httpx.Request) -> httpx.Response:
+            nonlocal call_count
+            if request.url.path == "/info":
+                call_count += 1
+                return httpx.Response(200, json={"model_id": "test-model"})
+            return httpx.Response(404)
+
+        transport = httpx.MockTransport(mock_handler)
+
+        with patch.object(httpx, "AsyncClient", return_value=httpx.AsyncClient(transport=transport)):
+            encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+            await encoder.initialize()
+            await encoder.initialize()
+            await encoder.initialize()
+
+            assert call_count == 1
+
+
+def create_mock_async_client(handler):
+    """Create a mock AsyncClient that uses the given handler for requests."""
+
+    class MockAsyncClient:
+        def __init__(self, **kwargs):
+            self.timeout = kwargs.get("timeout", 30.0)
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            pass
+
+        async def post(self, url, **kwargs):
+            return await handler("POST", url, **kwargs)
+
+        async def get(self, url, **kwargs):
+            return await handler("GET", url, **kwargs)
+
+    return MockAsyncClient()
+
+
+class TestRemoteTEICrossEncoderPredict:
+    """Tests for TEI cross-encoder predict functionality."""
+
+    @pytest.mark.asyncio
+    async def test_predict_not_initialized(self):
+        """Test predict raises error when not initialized."""
+        encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+
+        with pytest.raises(RuntimeError, match="Reranker not initialized"):
+            await encoder.predict([("query", "doc")])
+
+    @pytest.mark.asyncio
+    async def test_predict_empty_pairs(self):
+        """Test predict returns empty list for empty input."""
+        encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+        encoder._async_client = httpx.AsyncClient()
+        encoder._model_id = "test-model"
+
+        result = await encoder.predict([])
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_predict_single_query(self):
+        """Test predict with single query and multiple documents."""
+        rerank_calls = []
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                body = kwargs.get("json", {})
+                rerank_calls.append(body)
+                texts = body["texts"]
+                # Return scores in descending order with original indices
+                results = [{"index": i, "score": 1.0 - (i * 0.1)} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        pairs = [
+            ("What is Python?", "Python is a programming language."),
+            ("What is Python?", "Python is a snake."),
+            ("What is Python?", "Java is also a language."),
+        ]
+
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 3
+        assert len(rerank_calls) == 1
+        assert rerank_calls[0]["query"] == "What is Python?"
+        assert len(rerank_calls[0]["texts"]) == 3
+        # Scores should be mapped back correctly
+        assert scores[0] == 1.0
+        assert scores[1] == 0.9
+        assert scores[2] == pytest.approx(0.8, rel=0.01)
+
+    @pytest.mark.asyncio
+    async def test_predict_multiple_queries(self):
+        """Test predict with multiple different queries."""
+        rerank_calls = []
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                body = kwargs.get("json", {})
+                rerank_calls.append(body)
+                texts = body["texts"]
+                results = [{"index": i, "score": 0.5 + (i * 0.1)} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        pairs = [
+            ("Query A", "Doc A1"),
+            ("Query B", "Doc B1"),
+            ("Query A", "Doc A2"),
+            ("Query B", "Doc B2"),
+        ]
+
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 4
+        # Two queries = two rerank calls (run in parallel)
+        assert len(rerank_calls) == 2
+
+
+class TestRemoteTEICrossEncoderBatching:
+    """Tests for batch splitting behavior."""
+
+    @pytest.mark.asyncio
+    async def test_batch_splitting(self):
+        """Test that large inputs are split into batches."""
+        rerank_calls = []
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                body = kwargs.get("json", {})
+                rerank_calls.append(body)
+                texts = body["texts"]
+                results = [{"index": i, "score": 0.5} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            batch_size=3,  # Small batch for testing
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        # 7 documents with same query, batch_size=3 -> 3 batches (3+3+1)
+        pairs = [("Query", f"Doc {i}") for i in range(7)]
+
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 7
+        assert len(rerank_calls) == 3
+        # Check batch sizes
+        batch_sizes = sorted([len(call["texts"]) for call in rerank_calls])
+        assert batch_sizes == [1, 3, 3]
+
+    @pytest.mark.asyncio
+    async def test_score_mapping_across_batches(self):
+        """Test that scores are correctly mapped back across batches."""
+        call_counter = [0]
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                body = kwargs.get("json", {})
+                batch_num = call_counter[0]
+                call_counter[0] += 1
+                texts = body["texts"]
+                # Each batch returns different scores to verify mapping
+                base_score = batch_num * 10
+                results = [{"index": i, "score": float(base_score + i)} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            batch_size=3,
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        pairs = [("Query", f"Doc {i}") for i in range(7)]
+
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 7
+        # All scores should be present (exact values depend on batch ordering)
+        assert all(isinstance(s, (int, float)) for s in scores)
+
+
+class TestRemoteTEICrossEncoderParallelism:
+    """Tests for parallel request handling and backpressure."""
+
+    @pytest.mark.asyncio
+    async def test_parallel_requests(self):
+        """Test that requests are made in parallel."""
+        concurrent_count = [0]
+        max_concurrent_observed = [0]
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                concurrent_count[0] += 1
+                max_concurrent_observed[0] = max(max_concurrent_observed[0], concurrent_count[0])
+
+                await asyncio.sleep(0.03)  # Simulate latency
+
+                concurrent_count[0] -= 1
+                body = kwargs.get("json", {})
+                texts = body["texts"]
+                results = [{"index": i, "score": 0.5} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            batch_size=2,
+            max_concurrent=10,  # High limit to allow parallelism
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        # 6 docs = 3 batches, should run in parallel
+        pairs = [("Query", f"Doc {i}") for i in range(6)]
+
+        start = time.time()
+        scores = await encoder.predict(pairs)
+        elapsed = time.time() - start
+
+        assert len(scores) == 6
+        # If parallel, 3 batches with 30ms each should take ~30ms, not 90ms
+        assert elapsed < 0.08, f"Requests should run in parallel, took {elapsed}s"
+        assert max_concurrent_observed[0] > 1, "Multiple requests should run concurrently"
+
+    @pytest.mark.asyncio
+    async def test_backpressure_semaphore(self):
+        """Test that semaphore limits concurrent requests."""
+        concurrent_count = [0]
+        max_concurrent_observed = [0]
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                concurrent_count[0] += 1
+                max_concurrent_observed[0] = max(max_concurrent_observed[0], concurrent_count[0])
+
+                await asyncio.sleep(0.01)  # Simulate latency
+
+                concurrent_count[0] -= 1
+                body = kwargs.get("json", {})
+                texts = body["texts"]
+                results = [{"index": i, "score": 0.5} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        max_concurrent_limit = 2
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            batch_size=1,  # 1 doc per batch to maximize requests
+            max_concurrent=max_concurrent_limit,
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        # 10 docs = 10 batches, but only 2 should run at a time
+        pairs = [("Query", f"Doc {i}") for i in range(10)]
+
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 10
+        assert max_concurrent_observed[0] <= max_concurrent_limit, (
+            f"Semaphore should limit to {max_concurrent_limit}, observed {max_concurrent_observed[0]}"
+        )
+
+
+class TestRemoteTEICrossEncoderRetry:
+    """Tests for retry logic on transient errors."""
+
+    @pytest.mark.asyncio
+    async def test_retry_on_connect_error(self):
+        """Test that connect errors trigger retries."""
+        attempt_count = [0]
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                attempt_count[0] += 1
+                if attempt_count[0] < 3:
+                    raise httpx.ConnectError("Connection refused")
+                body = kwargs.get("json", {})
+                texts = body["texts"]
+                results = [{"index": i, "score": 0.5} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            max_retries=3,
+            retry_delay=0.01,
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        pairs = [("Query", "Doc 1")]
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 1
+        assert attempt_count[0] == 3  # 2 failures + 1 success
+
+    @pytest.mark.asyncio
+    async def test_retry_on_server_error(self):
+        """Test that 5xx errors trigger retries."""
+        attempt_count = [0]
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                attempt_count[0] += 1
+                if attempt_count[0] < 2:
+                    response = MagicMock()
+                    response.status_code = 503
+
+                    def raise_for_status():
+                        raise httpx.HTTPStatusError(
+                            "Service unavailable",
+                            request=MagicMock(),
+                            response=response,
+                        )
+
+                    response.raise_for_status = raise_for_status
+                    return response
+
+                body = kwargs.get("json", {})
+                texts = body["texts"]
+                results = [{"index": i, "score": 0.5} for i in range(len(texts))]
+                response = MagicMock()
+                response.status_code = 200
+                response.raise_for_status = MagicMock()
+                response.json = MagicMock(return_value=results)
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            max_retries=3,
+            retry_delay=0.01,
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        pairs = [("Query", "Doc 1")]
+        scores = await encoder.predict(pairs)
+
+        assert len(scores) == 1
+        assert attempt_count[0] == 2
+
+    @pytest.mark.asyncio
+    async def test_no_retry_on_client_error(self):
+        """Test that 4xx errors do not trigger retries."""
+        attempt_count = [0]
+
+        async def mock_handler(method, url, **kwargs):
+            if "/rerank" in url:
+                attempt_count[0] += 1
+                response = MagicMock()
+                response.status_code = 400
+
+                def raise_for_status():
+                    raise httpx.HTTPStatusError(
+                        "Bad request",
+                        request=MagicMock(),
+                        response=response,
+                    )
+
+                response.raise_for_status = raise_for_status
+                return response
+            raise httpx.HTTPStatusError("Not found", request=MagicMock(), response=MagicMock())
+
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            max_retries=3,
+            retry_delay=0.01,
+        )
+        encoder._async_client = create_mock_async_client(mock_handler)
+        encoder._model_id = "test-model"
+
+        pairs = [("Query", "Doc 1")]
+
+        with pytest.raises(RuntimeError, match="TEI rerank request failed"):
+            await encoder.predict(pairs)
+
+        assert attempt_count[0] == 1  # No retries for 4xx
+
+
+class TestRemoteTEICrossEncoderConfig:
+    """Tests for configuration from environment variables."""
+
+    def test_default_values(self):
+        """Test default configuration values."""
+        encoder = RemoteTEICrossEncoder(base_url="http://localhost:8080")
+
+        assert encoder.batch_size == 128
+        assert encoder.max_concurrent == 8
+        assert encoder.timeout == 30.0
+        assert encoder.max_retries == 3
+
+    def test_custom_values(self):
+        """Test custom configuration values."""
+        encoder = RemoteTEICrossEncoder(
+            base_url="http://localhost:8080",
+            batch_size=64,
+            max_concurrent=4,
+            timeout=60.0,
+            max_retries=5,
+            retry_delay=1.0,
+        )
+
+        assert encoder.batch_size == 64
+        assert encoder.max_concurrent == 4
+        assert encoder.timeout == 60.0
+        assert encoder.max_retries == 5
+        assert encoder.retry_delay == 1.0
+
+    def test_create_from_env(self):
+        """Test creating encoder from environment variables."""
+        import os
+
+        from hindsight_api.engine.cross_encoder import create_cross_encoder_from_env
+
+        with patch.dict(
+            os.environ,
+            {
+                "HINDSIGHT_API_RERANKER_PROVIDER": "tei",
+                "HINDSIGHT_API_RERANKER_TEI_URL": "http://test:9000",
+                "HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE": "256",
+                "HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT": "16",
+            },
+        ):
+            encoder = create_cross_encoder_from_env()
+
+            assert isinstance(encoder, RemoteTEICrossEncoder)
+            assert encoder.base_url == "http://test:9000"
+            assert encoder.batch_size == 256
+            assert encoder.max_concurrent == 16
+
+
+# ============================================================================
+# TEI Reranker Performance Benchmark Tests
+# ============================================================================
+# These tests require a running TEI server to measure actual performance.
+# Set TEI_RERANKER_URL environment variable to run.
+# Example:
+#   TEI_RERANKER_URL=http://localhost:8000 \
+#   pytest tests/test_tei_cross_encoder.py::test_tei_reranker_performance -v -s -n0
+
+import os
+
+TEI_RERANKER_URL = os.environ.get("TEI_RERANKER_URL")
+
+requires_tei_server = pytest.mark.skipif(
+    TEI_RERANKER_URL is None,
+    reason="TEI_RERANKER_URL not set - skipping TEI performance benchmark",
+)
+
+
+@requires_tei_server
+@pytest.mark.asyncio
+async def test_tei_reranker_performance():
+    """
+    Benchmark TEI reranker performance with different configurations.
+
+    This test measures latency for different batch sizes and concurrency levels
+    to find the optimal configuration for your TEI server.
+
+    Example usage:
+        TEI_RERANKER_URL=http://localhost:8000 \
+        pytest tests/test_tei_cross_encoder.py::test_tei_reranker_performance -v -s -n0
+    """
+    import httpx
+
+    # Get server info
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"{TEI_RERANKER_URL}/info")
+        info = response.json()
+        print(f"\n📊 TEI Server Info:")
+        print(f"   URL: {TEI_RERANKER_URL}")
+        print(f"   Model: {info.get('model_id', 'unknown')}")
+        if "reranker_model" in info:
+            print(f"   Reranker Model: {info['reranker_model']}")
+
+    # Generate test data (800 pairs to simulate real workload)
+    num_pairs = 800
+    query = "What did I say about training machine learning models and artificial intelligence?"
+    test_pairs = [
+        (query, f"Document {i} about machine learning, neural networks, and AI training techniques.")
+        for i in range(num_pairs)
+    ]
+
+    # Test configurations: (batch_size, max_concurrent)
+    configs = [
+        (128, 8),   # Default
+        (256, 4),   # Larger batches, fewer concurrent
+        (256, 8),   # Larger batches, same concurrent
+        (512, 2),   # Very large batches, few concurrent
+        (512, 4),   # Very large batches, moderate concurrent
+        (64, 16),   # Smaller batches, more concurrent
+        (800, 1),   # Single batch (all at once)
+    ]
+
+    results = []
+    print(f"\n⏱️  Benchmarking {num_pairs} pairs with different configurations:\n")
+
+    for batch_size, max_concurrent in configs:
+        encoder = RemoteTEICrossEncoder(
+            base_url=TEI_RERANKER_URL,
+            batch_size=batch_size,
+            max_concurrent=max_concurrent,
+            timeout=60.0,
+        )
+        await encoder.initialize()
+
+        # Warm-up run
+        await encoder.predict(test_pairs[:100])
+
+        # Timed runs (3 iterations)
+        times = []
+        for _ in range(3):
+            start = time.time()
+            scores = await encoder.predict(test_pairs)
+            elapsed = time.time() - start
+            times.append(elapsed)
+            assert len(scores) == num_pairs
+
+        avg_time = sum(times) / len(times)
+        min_time = min(times)
+        results.append({
+            "batch_size": batch_size,
+            "max_concurrent": max_concurrent,
+            "avg_ms": avg_time * 1000,
+            "min_ms": min_time * 1000,
+            "num_batches": (num_pairs + batch_size - 1) // batch_size,
+        })
+
+        print(f"   batch_size={batch_size:4d}, max_concurrent={max_concurrent:2d}: "
+              f"avg={avg_time * 1000:6.1f}ms, min={min_time * 1000:6.1f}ms "
+              f"({results[-1]['num_batches']} batches)")
+
+    # Find best configuration
+    best = min(results, key=lambda x: x["avg_ms"])
+    print(f"\n🏆 Best Configuration:")
+    print(f"   batch_size={best['batch_size']}, max_concurrent={best['max_concurrent']}")
+    print(f"   Average: {best['avg_ms']:.1f}ms, Min: {best['min_ms']:.1f}ms")
+
+    # Performance target check
+    target_ms = 100
+    if best["avg_ms"] <= target_ms:
+        print(f"\n✅ Target met! Average {best['avg_ms']:.1f}ms <= {target_ms}ms")
+    else:
+        print(f"\n⚠️ Target NOT met. Average {best['avg_ms']:.1f}ms > {target_ms}ms")
+        print(f"   Consider: larger batch size, GPU optimization, or faster network")
+
+
+@requires_tei_server
+@pytest.mark.asyncio
+async def test_tei_reranker_concurrent_requests():
+    """
+    Test TEI reranker performance under concurrent request load.
+
+    This simulates multiple parallel recall requests hitting the reranker
+    at the same time.
+    """
+    # Smaller batches to simulate typical recall workload
+    num_pairs_per_request = 200
+    num_concurrent_requests = 4
+
+    query = "Tell me about machine learning and AI training"
+    test_pairs = [
+        (query, f"Document {i} about ML and training.")
+        for i in range(num_pairs_per_request)
+    ]
+
+    # Test configurations
+    configs = [
+        (128, 8),   # Default
+        (256, 4),   # Larger batches
+        (512, 2),   # Very large batches
+        (200, 1),   # Single batch per request
+    ]
+
+    print(f"\n⏱️  Concurrent Load Test: {num_concurrent_requests} parallel requests, "
+          f"{num_pairs_per_request} pairs each:\n")
+
+    for batch_size, max_concurrent in configs:
+        encoder = RemoteTEICrossEncoder(
+            base_url=TEI_RERANKER_URL,
+            batch_size=batch_size,
+            max_concurrent=max_concurrent,
+            timeout=60.0,
+        )
+        await encoder.initialize()
+
+        # Warm-up
+        await encoder.predict(test_pairs[:50])
+
+        async def run_single_request():
+            start = time.time()
+            scores = await encoder.predict(test_pairs)
+            return time.time() - start, len(scores)
+
+        # Run concurrent requests
+        times = []
+        for _ in range(3):  # 3 iterations
+            start = time.time()
+            results = await asyncio.gather(*[run_single_request() for _ in range(num_concurrent_requests)])
+            total_time = time.time() - start
+
+            individual_times = [r[0] for r in results]
+            times.append({
+                "total": total_time,
+                "max_individual": max(individual_times),
+                "avg_individual": sum(individual_times) / len(individual_times),
+            })
+
+        avg_total = sum(t["total"] for t in times) / len(times)
+        avg_max_individual = sum(t["max_individual"] for t in times) / len(times)
+
+        print(f"   batch_size={batch_size:4d}, max_concurrent={max_concurrent:2d}: "
+              f"total={avg_total * 1000:6.1f}ms, slowest_req={avg_max_individual * 1000:6.1f}ms")
+
+
+@requires_tei_server
+@pytest.mark.asyncio
+async def test_tei_reranker_latency_breakdown():
+    """
+    Measure latency breakdown for TEI reranker requests.
+
+    This helps identify where time is spent: network vs processing.
+    """
+    import httpx
+
+    print(f"\n⏱️  Latency Breakdown Test:\n")
+
+    # Test single document latency (network overhead)
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        times = []
+        for _ in range(10):
+            start = time.time()
+            await client.post(
+                f"{TEI_RERANKER_URL}/rerank",
+                json={
+                    "query": "test query",
+                    "texts": ["test document"],
+                    "return_text": False,
+                },
+            )
+            times.append((time.time() - start) * 1000)
+
+        avg_single = sum(times) / len(times)
+        print(f"   Single doc latency (raw HTTP): {avg_single:.2f}ms")
+
+    # Test batch latencies
+    batch_sizes = [10, 50, 100, 200, 500]
+    for batch_size in batch_sizes:
+        texts = [f"Document {i} about machine learning" for i in range(batch_size)]
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            times = []
+            for _ in range(5):
+                start = time.time()
+                await client.post(
+                    f"{TEI_RERANKER_URL}/rerank",
+                    json={
+                        "query": "What about machine learning?",
+                        "texts": texts,
+                        "return_text": False,
+                    },
+                )
+                times.append((time.time() - start) * 1000)
+
+            avg = sum(times) / len(times)
+            per_doc = avg / batch_size
+            print(f"   Batch size {batch_size:4d}: {avg:6.1f}ms total, {per_doc:.2f}ms/doc")
+
+    print(f"\n   💡 Insight: Higher per-doc time at small batches = network overhead dominant")
+    print(f"   💡 Insight: Lower per-doc time at large batches = GPU efficiently utilized")
@@ -1,6 +1,6 @@
 [package]
 name = "hindsight-cli"
-version = "0.1.14"
+version = "0.2.1"
 edition = "2021"
 authors = ["Hindsight Team"]
 description = "A beautiful CLI for Hindsight - semantic memory system"
@@ -103,7 +103,7 @@ impl ApiClient {

    pub fn get_stats(&self, agent_id: &str, _verbose: bool) -> Result<AgentStats> {
        self.runtime.block_on(async {
-            let response = self.client.get_agent_stats(agent_id).await?;
+            let response = self.client.get_agent_stats(agent_id, None).await?;
            let value = response.into_inner();
            // Convert to JSON Value first, then parse into our type
            let json_value = serde_json::to_value(&value)?;
@@ -241,9 +241,9 @@ impl ApiClient {
        })
    }

-    pub fn list_entities(&self, bank_id: &str, limit: Option<i64>, _verbose: bool) -> Result<types::EntityListResponse> {
+    pub fn list_entities(&self, bank_id: &str, limit: Option<i64>, offset: Option<i64>, _verbose: bool) -> Result<types::EntityListResponse> {
        self.runtime.block_on(async {
-            let response = self.client.list_entities(bank_id, limit, None).await?;
+            let response = self.client.list_entities(bank_id, limit, offset, None).await?;
            Ok(response.into_inner())
        })
    }
@@ -16,7 +16,7 @@ pub fn list(
        None
    };

-    let response = client.list_entities(bank_id, Some(limit), verbose)?;
+    let response = client.list_entities(bank_id, Some(limit), None, verbose)?;

    if let Some(mut sp) = spinner {
        sp.finish();
@@ -5,7 +5,7 @@ use crossterm::{
    execute,
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
-use hindsight_client::types::{BankListItem, RecallResult, EntityListItem, Budget};
+use hindsight_client::types::{BankListItem, RecallResult, EntityListItem, Budget, TagsMatch};
 use serde_json::{Map, Value};
 use ratatui::{
    backend::{Backend, CrosstermBackend},
@@ -283,7 +283,7 @@ impl App {
    }

    fn load_entities(&mut self, bank_id: &str) -> Result<()> {
-        let response = self.client.list_entities(bank_id, Some(100), false)?;
+        let response = self.client.list_entities(bank_id, Some(100), None, false)?;
        self.entities = response.items;

        if !self.entities.is_empty() && self.entities_state.selected().is_none() {
@@ -341,6 +341,8 @@ impl App {
                            trace: false,
                            query_timestamp: None,
                            include: None,
+                            tags: None,
+                            tags_match: TagsMatch::Any,
                        };

                        let result = client.recall(&bank_id, &request, false)
@@ -354,7 +356,11 @@ impl App {
                            query: query_text,
                            budget: Some(query_budget),
                            context: None,
+                            max_tokens: 4096,
                            include: None,
+                            response_schema: None,
+                            tags: None,
+                            tags_match: TagsMatch::Any,
                        };

                        let result = client.reflect(&bank_id, &request, false)
@@ -9,7 +9,8 @@ use crate::output::{self, OutputFormat};
 use crate::ui;

 // Import types from generated client
-use hindsight_client::types::{Budget, ChunkIncludeOptions, IncludeOptions};
+use hindsight_client::types::{Budget, ChunkIncludeOptions, IncludeOptions, TagsMatch};
+use serde_json;

 // Helper function to parse budget string to Budget enum
 fn parse_budget(budget: &str) -> Budget {
@@ -59,6 +60,8 @@ pub fn recall(
        trace,
        query_timestamp: None,
        include,
+        tags: None,
+        tags_match: TagsMatch::Any,
    };

    let response = client.recall(agent_id, &request, verbose);
@@ -86,6 +89,8 @@ pub fn reflect(
    query: String,
    budget: String,
    context: Option<String>,
+    max_tokens: Option<i64>,
+    schema_path: Option<PathBuf>,
    verbose: bool,
    output_format: OutputFormat,
 ) -> Result<()> {
@@ -95,11 +100,26 @@ pub fn reflect(
        None
    };

+    // Load and parse schema if provided
+    let response_schema = if let Some(path) = schema_path {
+        let schema_content = fs::read_to_string(&path)
+            .with_context(|| format!("Failed to read schema file: {}", path.display()))?;
+        let schema: serde_json::Map<String, serde_json::Value> = serde_json::from_str(&schema_content)
+            .with_context(|| format!("Failed to parse JSON schema from: {}", path.display()))?;
+        Some(schema)
+    } else {
+        None
+    };
+
    let request = ReflectRequest {
        query,
        budget: Some(parse_budget(&budget)),
        context,
+        max_tokens: max_tokens.unwrap_or(4096),
        include: None,
+        response_schema,
+        tags: None,
+        tags_match: TagsMatch::Any,
    };

    let response = client.reflect(agent_id, &request, verbose);
@@ -145,11 +165,14 @@ pub fn retain(
        metadata: None,
        timestamp: None,
        document_id: Some(doc_id.clone()),
+        entities: None,
+        tags: None,
    };

    let request = RetainRequest {
        items: vec![item],
        async_: r#async,
+        document_tags: None,
    };

    let response = client.retain(agent_id, &request, r#async, verbose);
@@ -254,6 +277,8 @@ pub fn retain_files(
            metadata: None,
            timestamp: None,
            document_id: Some(doc_id),
+            entities: None,
+            tags: None,
        });

        pb.inc(1);
@@ -270,6 +295,7 @@ pub fn retain_files(
    let request = RetainRequest {
        items,
        async_: r#async,
+        document_tags: None,
    };

    let response = client.retain(agent_id, &request, r#async, verbose);
@@ -206,6 +206,14 @@ enum MemoryCommands {
        /// Additional context
        #[arg(short = 'c', long)]
        context: Option<String>,
+
+        /// Maximum tokens for the response (server default: 4096)
+        #[arg(short = 'm', long)]
+        max_tokens: Option<i64>,
+
+        /// Path to JSON schema file for structured output
+        #[arg(short = 's', long)]
+        schema: Option<PathBuf>,
    },

    /// Store (retain) a single memory
@@ -421,8 +429,8 @@ fn run() -> Result<()> {
            MemoryCommands::Recall { bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens } => {
                commands::memory::recall(&client, &bank_id, query, fact_type, budget, max_tokens, trace, include_chunks, chunk_max_tokens, verbose, output_format)
            }
-            MemoryCommands::Reflect { bank_id, query, budget, context } => {
-                commands::memory::reflect(&client, &bank_id, query, budget, context, verbose, output_format)
+            MemoryCommands::Reflect { bank_id, query, budget, context, max_tokens, schema } => {
+                commands::memory::reflect(&client, &bank_id, query, budget, context, max_tokens, schema, verbose, output_format)
            }
            MemoryCommands::Retain { bank_id, content, doc_id, context, r#async } => {
                commands::memory::retain(&client, &bank_id, content, doc_id, context, r#async, verbose, output_format)
@@ -175,6 +175,16 @@ pub fn print_think_response(response: &ReflectResponse) {
    if !response.based_on.is_empty() {
        println!("{}", dim(&format!("Based on {} memory units", response.based_on.len())));
    }
+
+    // Display structured output if present
+    if let Some(structured) = &response.structured_output {
+        println!();
+        println!("{}", gradient_text("─── Structured Output ───"));
+        println!();
+        if let Ok(json) = serde_json::to_string_pretty(structured) {
+            println!("{}", json);
+        }
+    }
 }

 pub fn print_trace_info(trace: &serde_json::Map<String, serde_json::Value>) {
@@ -9,54 +9,6 @@ hindsight_client_api/api/operations_api.py
 hindsight_client_api/api_client.py
 hindsight_client_api/api_response.py
 hindsight_client_api/configuration.py
-hindsight_client_api/docs/AddBackgroundRequest.md
-hindsight_client_api/docs/BackgroundResponse.md
-hindsight_client_api/docs/BankListItem.md
-hindsight_client_api/docs/BankListResponse.md
-hindsight_client_api/docs/BankProfileResponse.md
-hindsight_client_api/docs/BankStatsResponse.md
-hindsight_client_api/docs/BanksApi.md
-hindsight_client_api/docs/Budget.md
-hindsight_client_api/docs/CancelOperationResponse.md
-hindsight_client_api/docs/ChunkData.md
-hindsight_client_api/docs/ChunkIncludeOptions.md
-hindsight_client_api/docs/ChunkResponse.md
-hindsight_client_api/docs/CreateBankRequest.md
-hindsight_client_api/docs/DeleteDocumentResponse.md
-hindsight_client_api/docs/DeleteResponse.md
-hindsight_client_api/docs/DispositionTraits.md
-hindsight_client_api/docs/DocumentResponse.md
-hindsight_client_api/docs/DocumentsApi.md
-hindsight_client_api/docs/EntitiesApi.md
-hindsight_client_api/docs/EntityDetailResponse.md
-hindsight_client_api/docs/EntityIncludeOptions.md
-hindsight_client_api/docs/EntityListItem.md
-hindsight_client_api/docs/EntityListResponse.md
-hindsight_client_api/docs/EntityObservationResponse.md
-hindsight_client_api/docs/EntityStateResponse.md
-hindsight_client_api/docs/GraphDataResponse.md
-hindsight_client_api/docs/HTTPValidationError.md
-hindsight_client_api/docs/IncludeOptions.md
-hindsight_client_api/docs/ListDocumentsResponse.md
-hindsight_client_api/docs/ListMemoryUnitsResponse.md
-hindsight_client_api/docs/MemoryApi.md
-hindsight_client_api/docs/MemoryItem.md
-hindsight_client_api/docs/MonitoringApi.md
-hindsight_client_api/docs/OperationResponse.md
-hindsight_client_api/docs/OperationsApi.md
-hindsight_client_api/docs/OperationsListResponse.md
-hindsight_client_api/docs/RecallRequest.md
-hindsight_client_api/docs/RecallResponse.md
-hindsight_client_api/docs/RecallResult.md
-hindsight_client_api/docs/ReflectFact.md
-hindsight_client_api/docs/ReflectIncludeOptions.md
-hindsight_client_api/docs/ReflectRequest.md
-hindsight_client_api/docs/ReflectResponse.md
-hindsight_client_api/docs/RetainRequest.md
-hindsight_client_api/docs/RetainResponse.md
-hindsight_client_api/docs/UpdateDispositionRequest.md
-hindsight_client_api/docs/ValidationError.md
-hindsight_client_api/docs/ValidationErrorLocInner.md
 hindsight_client_api/exceptions.py
 hindsight_client_api/models/__init__.py
 hindsight_client_api/models/add_background_request.py
@@ -77,6 +29,7 @@ hindsight_client_api/models/disposition_traits.py
 hindsight_client_api/models/document_response.py
 hindsight_client_api/models/entity_detail_response.py
 hindsight_client_api/models/entity_include_options.py
+hindsight_client_api/models/entity_input.py
 hindsight_client_api/models/entity_list_item.py
 hindsight_client_api/models/entity_list_response.py
 hindsight_client_api/models/entity_observation_response.py
@@ -86,6 +39,7 @@ hindsight_client_api/models/http_validation_error.py
 hindsight_client_api/models/include_options.py
 hindsight_client_api/models/list_documents_response.py
 hindsight_client_api/models/list_memory_units_response.py
+hindsight_client_api/models/list_tags_response.py
 hindsight_client_api/models/memory_item.py
 hindsight_client_api/models/operation_response.py
 hindsight_client_api/models/operations_list_response.py
@@ -98,57 +52,10 @@ hindsight_client_api/models/reflect_request.py
 hindsight_client_api/models/reflect_response.py
 hindsight_client_api/models/retain_request.py
 hindsight_client_api/models/retain_response.py
+hindsight_client_api/models/tag_item.py
+hindsight_client_api/models/token_usage.py
 hindsight_client_api/models/update_disposition_request.py
 hindsight_client_api/models/validation_error.py
 hindsight_client_api/models/validation_error_loc_inner.py
 hindsight_client_api/rest.py
-hindsight_client_api/test/__init__.py
-hindsight_client_api/test/test_add_background_request.py
-hindsight_client_api/test/test_background_response.py
-hindsight_client_api/test/test_bank_list_item.py
-hindsight_client_api/test/test_bank_list_response.py
-hindsight_client_api/test/test_bank_profile_response.py
-hindsight_client_api/test/test_bank_stats_response.py
-hindsight_client_api/test/test_banks_api.py
-hindsight_client_api/test/test_budget.py
-hindsight_client_api/test/test_cancel_operation_response.py
-hindsight_client_api/test/test_chunk_data.py
-hindsight_client_api/test/test_chunk_include_options.py
-hindsight_client_api/test/test_chunk_response.py
-hindsight_client_api/test/test_create_bank_request.py
-hindsight_client_api/test/test_delete_document_response.py
-hindsight_client_api/test/test_delete_response.py
-hindsight_client_api/test/test_disposition_traits.py
-hindsight_client_api/test/test_document_response.py
-hindsight_client_api/test/test_documents_api.py
-hindsight_client_api/test/test_entities_api.py
-hindsight_client_api/test/test_entity_detail_response.py
-hindsight_client_api/test/test_entity_include_options.py
-hindsight_client_api/test/test_entity_list_item.py
-hindsight_client_api/test/test_entity_list_response.py
-hindsight_client_api/test/test_entity_observation_response.py
-hindsight_client_api/test/test_entity_state_response.py
-hindsight_client_api/test/test_graph_data_response.py
-hindsight_client_api/test/test_http_validation_error.py
-hindsight_client_api/test/test_include_options.py
-hindsight_client_api/test/test_list_documents_response.py
-hindsight_client_api/test/test_list_memory_units_response.py
-hindsight_client_api/test/test_memory_api.py
-hindsight_client_api/test/test_memory_item.py
-hindsight_client_api/test/test_monitoring_api.py
-hindsight_client_api/test/test_operation_response.py
-hindsight_client_api/test/test_operations_api.py
-hindsight_client_api/test/test_operations_list_response.py
-hindsight_client_api/test/test_recall_request.py
-hindsight_client_api/test/test_recall_response.py
-hindsight_client_api/test/test_recall_result.py
-hindsight_client_api/test/test_reflect_fact.py
-hindsight_client_api/test/test_reflect_include_options.py
-hindsight_client_api/test/test_reflect_request.py
-hindsight_client_api/test/test_reflect_response.py
-hindsight_client_api/test/test_retain_request.py
-hindsight_client_api/test/test_retain_response.py
-hindsight_client_api/test/test_update_disposition_request.py
-hindsight_client_api/test/test_validation_error.py
-hindsight_client_api/test/test_validation_error_loc_inner.py
 hindsight_client_api_README.md
@@ -1 +1 @@
-7.18.0-SNAPSHOT
+7.10.0
@@ -74,6 +74,8 @@ class Hindsight:
        """
        config = hindsight_client_api.Configuration(host=base_url, access_token=api_key)
        self._api_client = hindsight_client_api.ApiClient(config)
+        if api_key:
+            self._api_client.set_default_header("Authorization", f"Bearer {api_key}")
        self._memory_api = memory_api.MemoryApi(self._api_client)
        self._banks_api = banks_api.BanksApi(self._api_client)

@@ -112,6 +114,7 @@ class Hindsight:
        context: Optional[str] = None,
        document_id: Optional[str] = None,
        metadata: Optional[Dict[str, str]] = None,
+        entities: Optional[List[Dict[str, str]]] = None,
    ) -> RetainResponse:
        """
        Store a single memory (simplified interface).
@@ -123,13 +126,14 @@ class Hindsight:
            context: Optional context description
            document_id: Optional document ID for grouping
            metadata: Optional user-defined metadata
+            entities: Optional list of entities [{"text": "...", "type": "..."}]

        Returns:
            RetainResponse with success status
        """
        return self.retain_batch(
            bank_id=bank_id,
-            items=[{"content": content, "timestamp": timestamp, "context": context, "metadata": metadata}],
+            items=[{"content": content, "timestamp": timestamp, "context": context, "metadata": metadata, "entities": entities}],
            document_id=document_id,
        )

@@ -145,24 +149,34 @@ class Hindsight:

        Args:
            bank_id: The memory bank ID
-            items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id'
+            items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id', 'entities'
            document_id: Optional document ID for grouping memories (applied to items that don't have their own)
            retain_async: If True, process asynchronously in background (default: False)

        Returns:
            RetainResponse with success status and item count
        """
-        memory_items = [
-            memory_item.MemoryItem(
-                content=item["content"],
-                timestamp=item.get("timestamp"),
-                context=item.get("context"),
-                metadata=item.get("metadata"),
-                # Use item's document_id if provided, otherwise fall back to batch-level document_id
-                document_id=item.get("document_id") or document_id,
+        from hindsight_client_api.models.entity_input import EntityInput
+
+        memory_items = []
+        for item in items:
+            entities = None
+            if item.get("entities"):
+                entities = [
+                    EntityInput(text=e["text"], type=e.get("type"))
+                    for e in item["entities"]
+                ]
+            memory_items.append(
+                memory_item.MemoryItem(
+                    content=item["content"],
+                    timestamp=item.get("timestamp"),
+                    context=item.get("context"),
+                    metadata=item.get("metadata"),
+                    # Use item's document_id if provided, otherwise fall back to batch-level document_id
+                    document_id=item.get("document_id") or document_id,
+                    entities=entities,
+                )
            )
-            for item in items
-        ]

        request_obj = retain_request.RetainRequest(
            items=memory_items,
@@ -229,6 +243,8 @@ class Hindsight:
        query: str,
        budget: str = "low",
        context: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        response_schema: Optional[Dict[str, Any]] = None,
    ) -> ReflectResponse:
        """
        Generate a contextual answer based on bank identity and memories.
@@ -238,14 +254,21 @@ class Hindsight:
            query: The question or prompt
            budget: Budget level for reflection - "low", "mid", or "high" (default: "low")
            context: Optional additional context
+            max_tokens: Maximum tokens for the response (server default: 4096)
+            response_schema: Optional JSON Schema for structured output. When provided,
+                the response will include a 'structured_output' field with the LLM
+                response parsed according to this schema.

        Returns:
-            ReflectResponse with answer text and optionally facts used
+            ReflectResponse with answer text, optionally facts used, and optionally
+            structured_output if response_schema was provided
        """
        request_obj = reflect_request.ReflectRequest(
            query=query,
            budget=budget,
            context=context,
+            max_tokens=max_tokens,
+            response_schema=response_schema,
        )

        return _run_async(self._memory_api.reflect(bank_id, request_obj))
@@ -303,24 +326,34 @@ class Hindsight:

        Args:
            bank_id: The memory bank ID
-            items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id'
+            items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id', 'entities'
            document_id: Optional document ID for grouping memories (applied to items that don't have their own)
            retain_async: If True, process asynchronously in background (default: False)

        Returns:
            RetainResponse with success status and item count
        """
-        memory_items = [
-            memory_item.MemoryItem(
-                content=item["content"],
-                timestamp=item.get("timestamp"),
-                context=item.get("context"),
-                metadata=item.get("metadata"),
-                # Use item's document_id if provided, otherwise fall back to batch-level document_id
-                document_id=item.get("document_id") or document_id,
+        from hindsight_client_api.models.entity_input import EntityInput
+
+        memory_items = []
+        for item in items:
+            entities = None
+            if item.get("entities"):
+                entities = [
+                    EntityInput(text=e["text"], type=e.get("type"))
+                    for e in item["entities"]
+                ]
+            memory_items.append(
+                memory_item.MemoryItem(
+                    content=item["content"],
+                    timestamp=item.get("timestamp"),
+                    context=item.get("context"),
+                    metadata=item.get("metadata"),
+                    # Use item's document_id if provided, otherwise fall back to batch-level document_id
+                    document_id=item.get("document_id") or document_id,
+                    entities=entities,
+                )
            )
-            for item in items
-        ]

        request_obj = retain_request.RetainRequest(
            items=memory_items,
@@ -337,6 +370,7 @@ class Hindsight:
        context: Optional[str] = None,
        document_id: Optional[str] = None,
        metadata: Optional[Dict[str, str]] = None,
+        entities: Optional[List[Dict[str, str]]] = None,
    ) -> RetainResponse:
        """
        Store a single memory (async).
@@ -348,13 +382,14 @@ class Hindsight:
            context: Optional context description
            document_id: Optional document ID for grouping
            metadata: Optional user-defined metadata
+            entities: Optional list of entities [{"text": "...", "type": "..."}]

        Returns:
            RetainResponse with success status
        """
        return await self.aretain_batch(
            bank_id=bank_id,
-            items=[{"content": content, "timestamp": timestamp, "context": context, "metadata": metadata}],
+            items=[{"content": content, "timestamp": timestamp, "context": context, "metadata": metadata, "entities": entities}],
            document_id=document_id,
        )

@@ -16,127 +16,69 @@

 __version__ = "0.0.7"

-# Define package exports
-__all__ = [
-    "BanksApi",
-    "DocumentsApi",
-    "EntitiesApi",
-    "MemoryApi",
-    "MonitoringApi",
-    "OperationsApi",
-    "ApiResponse",
-    "ApiClient",
-    "Configuration",
-    "OpenApiException",
-    "ApiTypeError",
-    "ApiValueError",
-    "ApiKeyError",
-    "ApiAttributeError",
-    "ApiException",
-    "AddBackgroundRequest",
-    "BackgroundResponse",
-    "BankListItem",
-    "BankListResponse",
-    "BankProfileResponse",
-    "BankStatsResponse",
-    "Budget",
-    "CancelOperationResponse",
-    "ChunkData",
-    "ChunkIncludeOptions",
-    "ChunkResponse",
-    "CreateBankRequest",
-    "DeleteDocumentResponse",
-    "DeleteResponse",
-    "DispositionTraits",
-    "DocumentResponse",
-    "EntityDetailResponse",
-    "EntityIncludeOptions",
-    "EntityListItem",
-    "EntityListResponse",
-    "EntityObservationResponse",
-    "EntityStateResponse",
-    "GraphDataResponse",
-    "HTTPValidationError",
-    "IncludeOptions",
-    "ListDocumentsResponse",
-    "ListMemoryUnitsResponse",
-    "MemoryItem",
-    "OperationResponse",
-    "OperationsListResponse",
-    "RecallRequest",
-    "RecallResponse",
-    "RecallResult",
-    "ReflectFact",
-    "ReflectIncludeOptions",
-    "ReflectRequest",
-    "ReflectResponse",
-    "RetainRequest",
-    "RetainResponse",
-    "UpdateDispositionRequest",
-    "ValidationError",
-    "ValidationErrorLocInner",
-]
-
 # import apis into sdk package
-from hindsight_client_api.api.banks_api import BanksApi as BanksApi
-from hindsight_client_api.api.documents_api import DocumentsApi as DocumentsApi
-from hindsight_client_api.api.entities_api import EntitiesApi as EntitiesApi
-from hindsight_client_api.api.memory_api import MemoryApi as MemoryApi
-from hindsight_client_api.api.monitoring_api import MonitoringApi as MonitoringApi
-from hindsight_client_api.api.operations_api import OperationsApi as OperationsApi
+from hindsight_client_api.api.banks_api import BanksApi
+from hindsight_client_api.api.documents_api import DocumentsApi
+from hindsight_client_api.api.entities_api import EntitiesApi
+from hindsight_client_api.api.memory_api import MemoryApi
+from hindsight_client_api.api.monitoring_api import MonitoringApi
+from hindsight_client_api.api.operations_api import OperationsApi

 # import ApiClient
-from hindsight_client_api.api_response import ApiResponse as ApiResponse
-from hindsight_client_api.api_client import ApiClient as ApiClient
-from hindsight_client_api.configuration import Configuration as Configuration
-from hindsight_client_api.exceptions import OpenApiException as OpenApiException
-from hindsight_client_api.exceptions import ApiTypeError as ApiTypeError
-from hindsight_client_api.exceptions import ApiValueError as ApiValueError
-from hindsight_client_api.exceptions import ApiKeyError as ApiKeyError
-from hindsight_client_api.exceptions import ApiAttributeError as ApiAttributeError
-from hindsight_client_api.exceptions import ApiException as ApiException
+from hindsight_client_api.api_response import ApiResponse
+from hindsight_client_api.api_client import ApiClient
+from hindsight_client_api.configuration import Configuration
+from hindsight_client_api.exceptions import OpenApiException
+from hindsight_client_api.exceptions import ApiTypeError
+from hindsight_client_api.exceptions import ApiValueError
+from hindsight_client_api.exceptions import ApiKeyError
+from hindsight_client_api.exceptions import ApiAttributeError
+from hindsight_client_api.exceptions import ApiException

 # import models into sdk package
-from hindsight_client_api.models.add_background_request import AddBackgroundRequest as AddBackgroundRequest
-from hindsight_client_api.models.background_response import BackgroundResponse as BackgroundResponse
-from hindsight_client_api.models.bank_list_item import BankListItem as BankListItem
-from hindsight_client_api.models.bank_list_response import BankListResponse as BankListResponse
-from hindsight_client_api.models.bank_profile_response import BankProfileResponse as BankProfileResponse
-from hindsight_client_api.models.bank_stats_response import BankStatsResponse as BankStatsResponse
-from hindsight_client_api.models.budget import Budget as Budget
-from hindsight_client_api.models.cancel_operation_response import CancelOperationResponse as CancelOperationResponse
-from hindsight_client_api.models.chunk_data import ChunkData as ChunkData
-from hindsight_client_api.models.chunk_include_options import ChunkIncludeOptions as ChunkIncludeOptions
-from hindsight_client_api.models.chunk_response import ChunkResponse as ChunkResponse
-from hindsight_client_api.models.create_bank_request import CreateBankRequest as CreateBankRequest
-from hindsight_client_api.models.delete_document_response import DeleteDocumentResponse as DeleteDocumentResponse
-from hindsight_client_api.models.delete_response import DeleteResponse as DeleteResponse
-from hindsight_client_api.models.disposition_traits import DispositionTraits as DispositionTraits
-from hindsight_client_api.models.document_response import DocumentResponse as DocumentResponse
-from hindsight_client_api.models.entity_detail_response import EntityDetailResponse as EntityDetailResponse
-from hindsight_client_api.models.entity_include_options import EntityIncludeOptions as EntityIncludeOptions
-from hindsight_client_api.models.entity_list_item import EntityListItem as EntityListItem
-from hindsight_client_api.models.entity_list_response import EntityListResponse as EntityListResponse
-from hindsight_client_api.models.entity_observation_response import EntityObservationResponse as EntityObservationResponse
-from hindsight_client_api.models.entity_state_response import EntityStateResponse as EntityStateResponse
-from hindsight_client_api.models.graph_data_response import GraphDataResponse as GraphDataResponse
-from hindsight_client_api.models.http_validation_error import HTTPValidationError as HTTPValidationError
-from hindsight_client_api.models.include_options import IncludeOptions as IncludeOptions
-from hindsight_client_api.models.list_documents_response import ListDocumentsResponse as ListDocumentsResponse
-from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse as ListMemoryUnitsResponse
-from hindsight_client_api.models.memory_item import MemoryItem as MemoryItem
-from hindsight_client_api.models.operation_response import OperationResponse as OperationResponse
-from hindsight_client_api.models.operations_list_response import OperationsListResponse as OperationsListResponse
-from hindsight_client_api.models.recall_request import RecallRequest as RecallRequest
-from hindsight_client_api.models.recall_response import RecallResponse as RecallResponse
-from hindsight_client_api.models.recall_result import RecallResult as RecallResult
-from hindsight_client_api.models.reflect_fact import ReflectFact as ReflectFact
-from hindsight_client_api.models.reflect_include_options import ReflectIncludeOptions as ReflectIncludeOptions
-from hindsight_client_api.models.reflect_request import ReflectRequest as ReflectRequest
-from hindsight_client_api.models.reflect_response import ReflectResponse as ReflectResponse
-from hindsight_client_api.models.retain_request import RetainRequest as RetainRequest
-from hindsight_client_api.models.retain_response import RetainResponse as RetainResponse
-from hindsight_client_api.models.update_disposition_request import UpdateDispositionRequest as UpdateDispositionRequest
-from hindsight_client_api.models.validation_error import ValidationError as ValidationError
-from hindsight_client_api.models.validation_error_loc_inner import ValidationErrorLocInner as ValidationErrorLocInner
-
+from hindsight_client_api.models.add_background_request import AddBackgroundRequest
+from hindsight_client_api.models.background_response import BackgroundResponse
+from hindsight_client_api.models.bank_list_item import BankListItem
+from hindsight_client_api.models.bank_list_response import BankListResponse
+from hindsight_client_api.models.bank_profile_response import BankProfileResponse
+from hindsight_client_api.models.bank_stats_response import BankStatsResponse
+from hindsight_client_api.models.budget import Budget
+from hindsight_client_api.models.cancel_operation_response import CancelOperationResponse
+from hindsight_client_api.models.chunk_data import ChunkData
+from hindsight_client_api.models.chunk_include_options import ChunkIncludeOptions
+from hindsight_client_api.models.chunk_response import ChunkResponse
+from hindsight_client_api.models.create_bank_request import CreateBankRequest
+from hindsight_client_api.models.delete_document_response import DeleteDocumentResponse
+from hindsight_client_api.models.delete_response import DeleteResponse
+from hindsight_client_api.models.disposition_traits import DispositionTraits
+from hindsight_client_api.models.document_response import DocumentResponse
+from hindsight_client_api.models.entity_detail_response import EntityDetailResponse
+from hindsight_client_api.models.entity_include_options import EntityIncludeOptions
+from hindsight_client_api.models.entity_input import EntityInput
+from hindsight_client_api.models.entity_list_item import EntityListItem
+from hindsight_client_api.models.entity_list_response import EntityListResponse
+from hindsight_client_api.models.entity_observation_response import EntityObservationResponse
+from hindsight_client_api.models.entity_state_response import EntityStateResponse
+from hindsight_client_api.models.graph_data_response import GraphDataResponse
+from hindsight_client_api.models.http_validation_error import HTTPValidationError
+from hindsight_client_api.models.include_options import IncludeOptions
+from hindsight_client_api.models.list_documents_response import ListDocumentsResponse
+from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
+from hindsight_client_api.models.list_tags_response import ListTagsResponse
+from hindsight_client_api.models.memory_item import MemoryItem
+from hindsight_client_api.models.operation_response import OperationResponse
+from hindsight_client_api.models.operations_list_response import OperationsListResponse
+from hindsight_client_api.models.recall_request import RecallRequest
+from hindsight_client_api.models.recall_response import RecallResponse
+from hindsight_client_api.models.recall_result import RecallResult
+from hindsight_client_api.models.reflect_fact import ReflectFact
+from hindsight_client_api.models.reflect_include_options import ReflectIncludeOptions
+from hindsight_client_api.models.reflect_request import ReflectRequest
+from hindsight_client_api.models.reflect_response import ReflectResponse
+from hindsight_client_api.models.retain_request import RetainRequest
+from hindsight_client_api.models.retain_response import RetainResponse
+from hindsight_client_api.models.tag_item import TagItem
+from hindsight_client_api.models.token_usage import TokenUsage
+from hindsight_client_api.models.update_disposition_request import UpdateDispositionRequest
+from hindsight_client_api.models.validation_error import ValidationError
+from hindsight_client_api.models.validation_error_loc_inner import ValidationErrorLocInner
@@ -939,6 +939,7 @@ class BanksApi:
    async def get_agent_stats(
        self,
        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
@@ -958,6 +959,8 @@ class BanksApi:

        :param bank_id: (required)
        :type bank_id: str
+        :param authorization:
+        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
@@ -982,6 +985,7 @@ class BanksApi:

        _param = self._get_agent_stats_serialize(
            bank_id=bank_id,
+            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
@@ -1007,6 +1011,7 @@ class BanksApi:
    async def get_agent_stats_with_http_info(
        self,
        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
@@ -1026,6 +1031,8 @@ class BanksApi:

        :param bank_id: (required)
        :type bank_id: str
+        :param authorization:
+        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
@@ -1050,6 +1057,7 @@ class BanksApi:

        _param = self._get_agent_stats_serialize(
            bank_id=bank_id,
+            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
@@ -1075,6 +1083,7 @@ class BanksApi:
    async def get_agent_stats_without_preload_content(
        self,
        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
@@ -1094,6 +1103,8 @@ class BanksApi:

        :param bank_id: (required)
        :type bank_id: str
+        :param authorization:
+        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
@@ -1118,6 +1129,7 @@ class BanksApi:

        _param = self._get_agent_stats_serialize(
            bank_id=bank_id,
+            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
@@ -1138,6 +1150,7 @@ class BanksApi:
    def _get_agent_stats_serialize(
        self,
        bank_id,
+        authorization,
        _request_auth,
        _content_type,
        _headers,
@@ -1163,6 +1176,8 @@ class BanksApi:
            _path_params['bank_id'] = bank_id
        # process the query parameters
        # process the header parameters
+        if authorization is not None:
+            _header_params['authorization'] = authorization
        # process the form parameters
        # process the body parameter

@@ -338,6 +338,7 @@ class EntitiesApi:
        self,
        bank_id: StrictStr,
        limit: Annotated[Optional[StrictInt], Field(description="Maximum number of entities to return")] = None,
+        offset: Annotated[Optional[StrictInt], Field(description="Offset for pagination")] = None,
        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
@@ -354,12 +355,14 @@ class EntitiesApi:
    ) -> EntityListResponse:
        """List entities

-        List all entities (people, organizations, etc.) known by the bank, ordered by mention count.
+        List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.

        :param bank_id: (required)
        :type bank_id: str
        :param limit: Maximum number of entities to return
        :type limit: int
+        :param offset: Offset for pagination
+        :type offset: int
        :param authorization:
        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
@@ -387,6 +390,7 @@ class EntitiesApi:
        _param = self._list_entities_serialize(
            bank_id=bank_id,
            limit=limit,
+            offset=offset,
            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
@@ -414,6 +418,7 @@ class EntitiesApi:
        self,
        bank_id: StrictStr,
        limit: Annotated[Optional[StrictInt], Field(description="Maximum number of entities to return")] = None,
+        offset: Annotated[Optional[StrictInt], Field(description="Offset for pagination")] = None,
        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
@@ -430,12 +435,14 @@ class EntitiesApi:
    ) -> ApiResponse[EntityListResponse]:
        """List entities

-        List all entities (people, organizations, etc.) known by the bank, ordered by mention count.
+        List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.

        :param bank_id: (required)
        :type bank_id: str
        :param limit: Maximum number of entities to return
        :type limit: int
+        :param offset: Offset for pagination
+        :type offset: int
        :param authorization:
        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
@@ -463,6 +470,7 @@ class EntitiesApi:
        _param = self._list_entities_serialize(
            bank_id=bank_id,
            limit=limit,
+            offset=offset,
            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
@@ -490,6 +498,7 @@ class EntitiesApi:
        self,
        bank_id: StrictStr,
        limit: Annotated[Optional[StrictInt], Field(description="Maximum number of entities to return")] = None,
+        offset: Annotated[Optional[StrictInt], Field(description="Offset for pagination")] = None,
        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
@@ -506,12 +515,14 @@ class EntitiesApi:
    ) -> RESTResponseType:
        """List entities

-        List all entities (people, organizations, etc.) known by the bank, ordered by mention count.
+        List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.

        :param bank_id: (required)
        :type bank_id: str
        :param limit: Maximum number of entities to return
        :type limit: int
+        :param offset: Offset for pagination
+        :type offset: int
        :param authorization:
        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
@@ -539,6 +550,7 @@ class EntitiesApi:
        _param = self._list_entities_serialize(
            bank_id=bank_id,
            limit=limit,
+            offset=offset,
            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
@@ -561,6 +573,7 @@ class EntitiesApi:
        self,
        bank_id,
        limit,
+        offset,
        authorization,
        _request_auth,
        _content_type,
@@ -590,6 +603,10 @@ class EntitiesApi:
            
            _query_params.append(('limit', limit))
            
+        if offset is not None:
+            
+            _query_params.append(('offset', offset))
+            
        # process the header parameters
        if authorization is not None:
            _header_params['authorization'] = authorization
@@ -17,11 +17,12 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 from typing_extensions import Annotated

 from pydantic import Field, StrictInt, StrictStr
-from typing import Optional
+from typing import Any, Optional
 from typing_extensions import Annotated
 from hindsight_client_api.models.delete_response import DeleteResponse
 from hindsight_client_api.models.graph_data_response import GraphDataResponse
 from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
+from hindsight_client_api.models.list_tags_response import ListTagsResponse
 from hindsight_client_api.models.recall_request import RecallRequest
 from hindsight_client_api.models.recall_response import RecallResponse
 from hindsight_client_api.models.reflect_request import ReflectRequest
@@ -347,6 +348,7 @@ class MemoryApi:
        self,
        bank_id: StrictStr,
        type: Optional[StrictStr] = None,
+        limit: Optional[StrictInt] = None,
        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
@@ -363,12 +365,14 @@ class MemoryApi:
    ) -> GraphDataResponse:
        """Get memory graph data

-        Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.
+        Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion).

        :param bank_id: (required)
        :type bank_id: str
        :param type:
        :type type: str
+        :param limit:
+        :type limit: int
        :param authorization:
        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
@@ -396,6 +400,7 @@ class MemoryApi:
        _param = self._get_graph_serialize(
            bank_id=bank_id,
            type=type,
+            limit=limit,
            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
@@ -423,6 +428,7 @@ class MemoryApi:
        self,
        bank_id: StrictStr,
        type: Optional[StrictStr] = None,
+        limit: Optional[StrictInt] = None,
        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
@@ -439,12 +445,14 @@ class MemoryApi:
    ) -> ApiResponse[GraphDataResponse]:
        """Get memory graph data

-        Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.
+        Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion).

        :param bank_id: (required)
        :type bank_id: str
        :param type:
        :type type: str
+        :param limit:
+        :type limit: int
        :param authorization:
        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
@@ -472,6 +480,7 @@ class MemoryApi:
        _param = self._get_graph_serialize(
            bank_id=bank_id,
            type=type,
+            limit=limit,
            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
@@ -499,6 +508,7 @@ class MemoryApi:
        self,
        bank_id: StrictStr,
        type: Optional[StrictStr] = None,
+        limit: Optional[StrictInt] = None,
        authorization: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
@@ -515,12 +525,14 @@ class MemoryApi:
    ) -> RESTResponseType:
        """Get memory graph data

-        Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.
+        Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion).

        :param bank_id: (required)
        :type bank_id: str
        :param type:
        :type type: str
+        :param limit:
+        :type limit: int
        :param authorization:
        :type authorization: str
        :param _request_timeout: timeout setting for this request. If one
@@ -548,6 +560,7 @@ class MemoryApi:
        _param = self._get_graph_serialize(
            bank_id=bank_id,
            type=type,
+            limit=limit,
            authorization=authorization,
            _request_auth=_request_auth,
            _content_type=_content_type,
@@ -570,6 +583,7 @@ class MemoryApi:
        self,
        bank_id,
        type,
+        limit,
        authorization,
        _request_auth,
        _content_type,
@@ -599,6 +613,10 @@ class MemoryApi:
            
            _query_params.append(('type', type))
            
+        if limit is not None:
+            
+            _query_params.append(('limit', limit))
+            
        # process the header parameters
        if authorization is not None:
            _header_params['authorization'] = authorization
@@ -637,6 +655,299 @@ class MemoryApi:



+    @validate_call
+    async def get_memory(
+        self,
+        bank_id: StrictStr,
+        memory_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> object:
+        """Get memory unit
+
+        Get a single memory unit by ID with all its metadata including entities and tags.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param memory_id: (required)
+        :type memory_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_memory_serialize(
+            bank_id=bank_id,
+            memory_id=memory_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "object",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        ).data
+
+
+    @validate_call
+    async def get_memory_with_http_info(
+        self,
+        bank_id: StrictStr,
+        memory_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ApiResponse[object]:
+        """Get memory unit
+
+        Get a single memory unit by ID with all its metadata including entities and tags.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param memory_id: (required)
+        :type memory_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_memory_serialize(
+            bank_id=bank_id,
+            memory_id=memory_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "object",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        )
+
+
+    @validate_call
+    async def get_memory_without_preload_content(
+        self,
+        bank_id: StrictStr,
+        memory_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> RESTResponseType:
+        """Get memory unit
+
+        Get a single memory unit by ID with all its metadata including entities and tags.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param memory_id: (required)
+        :type memory_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_memory_serialize(
+            bank_id=bank_id,
+            memory_id=memory_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "object",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        return response_data.response
+
+
+    def _get_memory_serialize(
+        self,
+        bank_id,
+        memory_id,
+        authorization,
+        _request_auth,
+        _content_type,
+        _headers,
+        _host_index,
+    ) -> RequestSerialized:
+
+        _host = None
+
+        _collection_formats: Dict[str, str] = {
+        }
+
+        _path_params: Dict[str, str] = {}
+        _query_params: List[Tuple[str, str]] = []
+        _header_params: Dict[str, Optional[str]] = _headers or {}
+        _form_params: List[Tuple[str, str]] = []
+        _files: Dict[
+            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
+        ] = {}
+        _body_params: Optional[bytes] = None
+
+        # process the path parameters
+        if bank_id is not None:
+            _path_params['bank_id'] = bank_id
+        if memory_id is not None:
+            _path_params['memory_id'] = memory_id
+        # process the query parameters
+        # process the header parameters
+        if authorization is not None:
+            _header_params['authorization'] = authorization
+        # process the form parameters
+        # process the body parameter
+
+
+        # set the HTTP header `Accept`
+        if 'Accept' not in _header_params:
+            _header_params['Accept'] = self.api_client.select_header_accept(
+                [
+                    'application/json'
+                ]
+            )
+
+
+        # authentication setting
+        _auth_settings: List[str] = [
+        ]
+
+        return self.api_client.param_serialize(
+            method='GET',
+            resource_path='/v1/default/banks/{bank_id}/memories/{memory_id}',
+            path_params=_path_params,
+            query_params=_query_params,
+            header_params=_header_params,
+            body=_body_params,
+            post_params=_form_params,
+            files=_files,
+            auth_settings=_auth_settings,
+            collection_formats=_collection_formats,
+            _host=_host,
+            _request_auth=_request_auth
+        )
+
+
+
+
    @validate_call
    async def list_memories(
        self,
@@ -983,6 +1294,335 @@ class MemoryApi:



+    @validate_call
+    async def list_tags(
+        self,
+        bank_id: StrictStr,
+        q: Annotated[Optional[StrictStr], Field(description="Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.")] = None,
+        limit: Annotated[Optional[StrictInt], Field(description="Maximum number of tags to return")] = None,
+        offset: Annotated[Optional[StrictInt], Field(description="Offset for pagination")] = None,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ListTagsResponse:
+        """List tags
+
+        List all unique tags in a memory bank with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param q: Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.
+        :type q: str
+        :param limit: Maximum number of tags to return
+        :type limit: int
+        :param offset: Offset for pagination
+        :type offset: int
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._list_tags_serialize(
+            bank_id=bank_id,
+            q=q,
+            limit=limit,
+            offset=offset,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "ListTagsResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        ).data
+
+
+    @validate_call
+    async def list_tags_with_http_info(
+        self,
+        bank_id: StrictStr,
+        q: Annotated[Optional[StrictStr], Field(description="Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.")] = None,
+        limit: Annotated[Optional[StrictInt], Field(description="Maximum number of tags to return")] = None,
+        offset: Annotated[Optional[StrictInt], Field(description="Offset for pagination")] = None,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ApiResponse[ListTagsResponse]:
+        """List tags
+
+        List all unique tags in a memory bank with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param q: Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.
+        :type q: str
+        :param limit: Maximum number of tags to return
+        :type limit: int
+        :param offset: Offset for pagination
+        :type offset: int
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._list_tags_serialize(
+            bank_id=bank_id,
+            q=q,
+            limit=limit,
+            offset=offset,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "ListTagsResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        )
+
+
+    @validate_call
+    async def list_tags_without_preload_content(
+        self,
+        bank_id: StrictStr,
+        q: Annotated[Optional[StrictStr], Field(description="Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.")] = None,
+        limit: Annotated[Optional[StrictInt], Field(description="Maximum number of tags to return")] = None,
+        offset: Annotated[Optional[StrictInt], Field(description="Offset for pagination")] = None,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> RESTResponseType:
+        """List tags
+
+        List all unique tags in a memory bank with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param q: Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.
+        :type q: str
+        :param limit: Maximum number of tags to return
+        :type limit: int
+        :param offset: Offset for pagination
+        :type offset: int
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._list_tags_serialize(
+            bank_id=bank_id,
+            q=q,
+            limit=limit,
+            offset=offset,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "ListTagsResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        return response_data.response
+
+
+    def _list_tags_serialize(
+        self,
+        bank_id,
+        q,
+        limit,
+        offset,
+        authorization,
+        _request_auth,
+        _content_type,
+        _headers,
+        _host_index,
+    ) -> RequestSerialized:
+
+        _host = None
+
+        _collection_formats: Dict[str, str] = {
+        }
+
+        _path_params: Dict[str, str] = {}
+        _query_params: List[Tuple[str, str]] = []
+        _header_params: Dict[str, Optional[str]] = _headers or {}
+        _form_params: List[Tuple[str, str]] = []
+        _files: Dict[
+            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
+        ] = {}
+        _body_params: Optional[bytes] = None
+
+        # process the path parameters
+        if bank_id is not None:
+            _path_params['bank_id'] = bank_id
+        # process the query parameters
+        if q is not None:
+            
+            _query_params.append(('q', q))
+            
+        if limit is not None:
+            
+            _query_params.append(('limit', limit))
+            
+        if offset is not None:
+            
+            _query_params.append(('offset', offset))
+            
+        # process the header parameters
+        if authorization is not None:
+            _header_params['authorization'] = authorization
+        # process the form parameters
+        # process the body parameter
+
+
+        # set the HTTP header `Accept`
+        if 'Accept' not in _header_params:
+            _header_params['Accept'] = self.api_client.select_header_accept(
+                [
+                    'application/json'
+                ]
+            )
+
+
+        # authentication setting
+        _auth_settings: List[str] = [
+        ]
+
+        return self.api_client.param_serialize(
+            method='GET',
+            resource_path='/v1/default/banks/{bank_id}/tags',
+            path_params=_path_params,
+            query_params=_query_params,
+            header_params=_header_params,
+            body=_body_params,
+            post_params=_form_params,
+            files=_files,
+            auth_settings=_auth_settings,
+            collection_formats=_collection_formats,
+            _host=_host,
+            _request_auth=_request_auth
+        )
+
+
+
+
    @validate_call
    async def recall_memories(
        self,
@@ -21,7 +21,6 @@ import mimetypes
 import os
 import re
 import tempfile
-import uuid

 from urllib.parse import quote
 from typing import Tuple, Optional, List, Dict, Union
@@ -360,8 +359,6 @@ class ApiClient:
            return obj.get_secret_value()
        elif isinstance(obj, self.PRIMITIVE_TYPES):
            return obj
-        elif isinstance(obj, uuid.UUID):
-            return str(obj)
        elif isinstance(obj, list):
            return [
                self.sanitize_for_serialization(sub_obj) for sub_obj in obj
@@ -388,10 +385,6 @@ class ApiClient:
            else:
                obj_dict = obj.__dict__

-        if isinstance(obj_dict, list):
-            # here we handle instances that can either be a list or something else, and only became a real list by calling to_dict()
-            return self.sanitize_for_serialization(obj_dict)
-
        return {
            key: self.sanitize_for_serialization(val)
            for key, val in obj_dict.items()
@@ -414,7 +407,7 @@ class ApiClient:
                data = json.loads(response_text)
            except ValueError:
                data = response_text
-        elif re.match(r'^application/(json|[\w!#$&.+\-^_]+\+json)\s*(;|$)', content_type, re.IGNORECASE):
+        elif re.match(r'^application/(json|[\w!#$&.+-^_]+\+json)\s*(;|$)', content_type, re.IGNORECASE):
            if response_text == "":
                data = ""
            else:
@@ -463,13 +456,13 @@ class ApiClient:

        if klass in self.PRIMITIVE_TYPES:
            return self.__deserialize_primitive(data, klass)
-        elif klass is object:
+        elif klass == object:
            return self.__deserialize_object(data)
-        elif klass is datetime.date:
+        elif klass == datetime.date:
            return self.__deserialize_date(data)
-        elif klass is datetime.datetime:
+        elif klass == datetime.datetime:
            return self.__deserialize_datetime(data)
-        elif klass is decimal.Decimal:
+        elif klass == decimal.Decimal:
            return decimal.Decimal(data)
        elif issubclass(klass, Enum):
            return self.__deserialize_enum(data, klass)
@@ -527,7 +520,7 @@ class ApiClient:
            if k in collection_formats:
                collection_format = collection_formats[k]
                if collection_format == 'multi':
-                    new_params.extend((k, quote(str(value))) for value in v)
+                    new_params.extend((k, str(value)) for value in v)
                else:
                    if collection_format == 'ssv':
                        delimiter = ' '
@@ -17,7 +17,7 @@ import http.client as httplib
 import logging
 from logging import FileHandler
 import sys
-from typing import Any, ClassVar, Dict, List, Literal, Optional, TypedDict, Union
+from typing import Any, ClassVar, Dict, List, Literal, Optional, TypedDict
 from typing_extensions import NotRequired, Self

 import urllib3
@@ -159,10 +159,6 @@ class Configuration:
    :param ssl_ca_cert: str - the path to a file of concatenated CA certificates
      in PEM format.
    :param retries: Number of retries for API requests.
-    :param ca_cert_data: verify the peer using concatenated CA certificate data
-      in PEM (str) or DER (bytes) format.
-    :param cert_file: the path to a client certificate file, for mTLS.
-    :param key_file: the path to a client key file, for mTLS. 

    """

@@ -176,16 +172,13 @@ class Configuration:
        username: Optional[str]=None,
        password: Optional[str]=None,
        access_token: Optional[str]=None,
-        server_index: Optional[int]=None,
+        server_index: Optional[int]=None, 
        server_variables: Optional[ServerVariablesT]=None,
        server_operation_index: Optional[Dict[int, int]]=None,
        server_operation_variables: Optional[Dict[int, ServerVariablesT]]=None,
        ignore_operation_servers: bool=False,
        ssl_ca_cert: Optional[str]=None,
        retries: Optional[int] = None,
-        ca_cert_data: Optional[Union[str, bytes]] = None,
-        cert_file: Optional[str]=None,
-        key_file: Optional[str]=None,
        *,
        debug: Optional[bool] = None,
    ) -> None:
@@ -263,14 +256,10 @@ class Configuration:
        self.ssl_ca_cert = ssl_ca_cert
        """Set this to customize the certificate file to verify the peer.
        """
-        self.ca_cert_data = ca_cert_data
-        """Set this to verify the peer using PEM (str) or DER (bytes)
-           certificate data.
-        """
-        self.cert_file = cert_file
+        self.cert_file = None
        """client certificate file
        """
-        self.key_file = key_file
+        self.key_file = None
        """client key file
        """
        self.assert_hostname = None
--- a/Show More
+++ b/Show More