fix: create report.pdf in working directory for retain.sh file upload examples

fix: add include_facts to reflect client, fix retain.sh temp files, fix main-methods based_on access
doc: improve api explanation
2026-02-20 15:40:35 +01:00 · 2026-02-20 15:18:11 +01:00 · 2026-02-20 15:12:22 +01:00 · 2026-02-20 14:37:11 +01:00 · 2026-02-20 14:36:53 +01:00 · 2026-02-20 09:31:46 +01:00
347 changed files with 12650 additions and 4265 deletions
@@ -5,7 +5,7 @@
 # Supported providers: openai, groq, ollama, gemini, anthropic, lmstudio, vertexai
 HINDSIGHT_API_LLM_PROVIDER=openai
 HINDSIGHT_API_LLM_API_KEY=your-api-key-here
-HINDSIGHT_API_LLM_MODEL=o3-mini
+HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
 HINDSIGHT_API_LLM_BASE_URL=https://api.openai.com/v1

 # Example: Anthropic Claude configuration
@@ -46,6 +46,10 @@ jobs:
      working-directory: ./hindsight-embed
      run: uv build --out-dir dist

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

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

  release-typescript-client:
@@ -268,11 +279,14 @@ jobs:
    - name: Build
      run: npm run build --workspace=hindsight-control-plane

+    - name: Verify standalone build
+      run: test -f hindsight-control-plane/standalone/server.js || (echo 'standalone/server.js missing - build failed' && exit 1)
+
    - name: Publish to npm
      working-directory: ./hindsight-control-plane
      run: |
        set +e
-        OUTPUT=$(npm publish --access public 2>&1)
+        OUTPUT=$(npm publish --access public --ignore-scripts 2>&1)
        EXIT_CODE=$?
        echo "$OUTPUT"
        if [ $EXIT_CODE -ne 0 ]; then
@@ -171,9 +171,9 @@ jobs:
  test-rust-cli:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -343,7 +343,9 @@ jobs:
    - name: Smoke test - verify container starts
      if: matrix.variant == 'slim'
      env:
-        GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+        HINDSIGHT_API_LLM_PROVIDER: openai
+        HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
        HINDSIGHT_API_EMBEDDINGS_PROVIDER: openai
        HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        HINDSIGHT_API_RERANKER_PROVIDER: cohere
@@ -353,14 +355,13 @@ jobs:
  test-api:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_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
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -414,9 +415,9 @@ jobs:
  test-python-client:
    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_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -490,9 +491,9 @@ jobs:
  test-typescript-client:
    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_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -571,9 +572,9 @@ jobs:
  test-rust-client:
    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_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -651,9 +652,9 @@ jobs:
  test-go-client:
    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_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -712,6 +713,10 @@ jobs:
          sleep 1
        done

+    - name: Build Go client
+      working-directory: ./hindsight-clients/go
+      run: go build ./...
+
    - name: Run Go client tests
      working-directory: ./hindsight-clients/go
      run: go test -v -tags=integration
@@ -722,12 +727,113 @@ jobs:
        echo "=== API Server Logs ==="
        cat /tmp/api-server.log || echo "No API server log found"

+  test-openclaw-integration:
+    runs-on: ubuntu-latest
+    env:
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
+      HINDSIGHT_API_URL: http://localhost:8888
+      HINDSIGHT_EMBED_PACKAGE_PATH: ${{ github.workspace }}/hindsight-embed
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        prune-cache: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+
+    - name: Build API
+      working-directory: ./hindsight-api
+      run: uv build
+
+    - name: Install API dependencies
+      working-directory: ./hindsight-api
+      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
+
+    - name: Install embed dependencies
+      working-directory: ./hindsight-embed
+      run: uv sync --frozen --index-strategy unsafe-best-match
+
+    - name: Cache HuggingFace models
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/huggingface
+        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-huggingface-
+
+    - name: Pre-download models
+      working-directory: ./hindsight-api
+      run: |
+        uv run python -c "
+        from sentence_transformers import SentenceTransformer, CrossEncoder
+        print('Downloading embedding model...')
+        SentenceTransformer('BAAI/bge-small-en-v1.5')
+        print('Downloading cross-encoder model...')
+        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
+        print('Models downloaded successfully')
+        "
+
+    - name: Install openclaw integration dependencies
+      working-directory: ./hindsight-integrations/openclaw
+      run: npm ci
+
+    - name: Create .env file
+      run: |
+        cat > .env << EOF
+        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_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 openclaw integration tests
+      working-directory: ./hindsight-integrations/openclaw
+      run: npm run test:integration
+
+    - name: Show API server logs
+      if: always()
+      run: |
+        echo "=== API Server Logs ==="
+        cat /tmp/api-server.log || echo "No API server log found"
+
  test-integration:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -813,6 +919,35 @@ jobs:
        echo "=== API Server Logs ==="
        cat /tmp/api-server.log || echo "No API server log found"

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

@@ -845,9 +980,9 @@ jobs:
  test-embed:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      # Prefer CPU-only PyTorch in CI
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

@@ -889,13 +1024,13 @@ jobs:
  test-hindsight-all:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      # For test_server_integration.py compatibility
-      HINDSIGHT_LLM_PROVIDER: groq
-      HINDSIGHT_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_LLM_PROVIDER: openai
+      HINDSIGHT_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_LLM_MODEL: gpt-4o-mini
      # Prefer CPU-only PyTorch in CI
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

@@ -938,9 +1073,9 @@ jobs:
    runs-on: ubuntu-latest
    needs: test-rust-cli
    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
+      HINDSIGHT_API_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -1030,9 +1165,9 @@ jobs:
  test-upgrade:
    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_LLM_PROVIDER: openai
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

@@ -317,7 +317,7 @@ 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)
+- `HINDSIGHT_API_LLM_MODEL`: Model name (e.g., gpt-4o-mini, claude-sonnet-4-20250514)

 Optional (uses local models by default):
 - `HINDSIGHT_API_EMBEDDINGS_PROVIDER`: local (default) or tei
@@ -170,6 +170,11 @@ RUN chown -R hindsight:hindsight /app

 USER hindsight

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

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

 USER hindsight

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

 # Pre-download tiktoken encoding (ALWAYS - required for token counting even in air-gapped envs)
@@ -13,9 +13,9 @@
 #   target  - Optional: 'cp-only' for control plane, otherwise assumes API image (default: api)
 #
 # Environment variables:
-#   GROQ_API_KEY                                - Required for API/standalone images (LLM verification)
-#   HINDSIGHT_API_LLM_PROVIDER                  - LLM provider (default: groq)
-#   HINDSIGHT_API_LLM_MODEL                     - LLM model (default: llama-3.3-70b-versatile)
+#   HINDSIGHT_API_LLM_API_KEY                   - Required for API/standalone images (LLM verification)
+#   HINDSIGHT_API_LLM_PROVIDER                  - LLM provider (default: openai)
+#   HINDSIGHT_API_LLM_MODEL                     - LLM model (default: gpt-4o-mini)
 #   HINDSIGHT_API_EMBEDDINGS_PROVIDER           - Embeddings provider (optional, for slim images: openai, cohere, tei)
 #   HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY     - OpenAI API key for embeddings (optional)
 #   HINDSIGHT_API_RERANKER_PROVIDER             - Reranker provider (optional, for slim images: cohere, tei)
@@ -34,7 +34,7 @@
 #   ./docker/test-image.sh hindsight-control-plane:test cp-only
 #
 #   # Test slim image with external providers
-#   export GROQ_API_KEY=gsk_xxx
+#   export HINDSIGHT_API_LLM_API_KEY=sk_xxx
 #   export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
 #   export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=sk-xxx
 #   export HINDSIGHT_API_RERANKER_PROVIDER=cohere
@@ -60,8 +60,8 @@ IMAGE="${1:-}"
 TARGET="${2:-api}"
 TIMEOUT="${SMOKE_TEST_TIMEOUT:-120}"
 CONTAINER_NAME="${SMOKE_TEST_CONTAINER_NAME:-hindsight-smoke-test}"
-LLM_PROVIDER="${HINDSIGHT_API_LLM_PROVIDER:-groq}"
-LLM_MODEL="${HINDSIGHT_API_LLM_MODEL:-llama-3.3-70b-versatile}"
+LLM_PROVIDER="${HINDSIGHT_API_LLM_PROVIDER:-openai}"
+LLM_MODEL="${HINDSIGHT_API_LLM_MODEL:-gpt-4o-mini}"

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

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

@@ -123,7 +123,7 @@ else
    # Build docker run command with required and optional env vars
    DOCKER_CMD="docker run -d --name $CONTAINER_NAME"
    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_PROVIDER=$LLM_PROVIDER"
-    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_API_KEY=${GROQ_API_KEY}"
+    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_API_LLM_API_KEY}"
    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_MODEL=$LLM_MODEL"

    # Add optional embeddings provider config
@@ -6,24 +6,17 @@
 # It expects API keys to be set in environment variables.
 #
 # Usage:
-#   export GROQ_API_KEY=gsk_xxx
 #   export OPENAI_API_KEY=sk-xxx
 #   export COHERE_API_KEY=xxx
 #   ./docker/test-slim-local.sh
 #
 # Or inline:
-#   GROQ_API_KEY=gsk_xxx OPENAI_API_KEY=sk_xxx COHERE_API_KEY=xxx ./docker/test-slim-local.sh
+#   OPENAI_API_KEY=sk_xxx COHERE_API_KEY=xxx ./docker/test-slim-local.sh
 #

 set -euo pipefail

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

-# Set up external providers
+# Set up LLM and external providers
+export HINDSIGHT_API_LLM_PROVIDER=openai
+export HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY
+export HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
 export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=$OPENAI_API_KEY
 export HINDSIGHT_API_RERANKER_PROVIDER=cohere
@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.11
-appVersion: "0.4.11"
+version: 0.4.13
+appVersion: "0.4.13"
 keywords:
  - ai
  - memory
@@ -46,4 +46,4 @@ __all__ = [
    "RemoteTEICrossEncoder",
    "LLMConfig",
 ]
-__version__ = "0.4.11"
+__version__ = "0.4.13"
@@ -74,7 +74,7 @@ from hindsight_api.config import get_config
 from hindsight_api.engine.db_utils import acquire_with_retry
 from hindsight_api.engine.memory_engine import Budget, _get_tiktoken_encoding, fq_table
 from hindsight_api.engine.reflect.observations import Observation
-from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES, TokenUsage
+from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES, MemoryFact, 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
@@ -97,6 +97,12 @@ class ChunkIncludeOptions(BaseModel):
    max_tokens: int = Field(default=8192, description="Maximum tokens for chunks (chunks may be truncated)")


+class SourceFactsIncludeOptions(BaseModel):
+    """Options for including source facts for observation-type results."""
+
+    max_tokens: int = Field(default=4096, description="Maximum tokens for source facts")
+
+
 class IncludeOptions(BaseModel):
    """Options for including additional data in recall results."""

@@ -107,6 +113,10 @@ class IncludeOptions(BaseModel):
    chunks: ChunkIncludeOptions | None = Field(
        default=None, description="Include raw chunks. Set to {} to enable, null to disable (default: disabled)."
    )
+    source_facts: SourceFactsIncludeOptions | None = Field(
+        default=None,
+        description="Include source facts for observation-type results. Set to {} to enable, null to disable (default: disabled).",
+    )


 class RecallRequest(BaseModel):
@@ -189,6 +199,9 @@ class RecallResult(BaseModel):
    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
+    source_fact_ids: list[str] | None = (
+        None  # IDs of source facts (observation type only, when source_facts is enabled)
+    )


 class EntityObservationResponse(BaseModel):
@@ -340,6 +353,9 @@ class RecallResponse(BaseModel):
        default=None, description="Entity states for entities mentioned in results"
    )
    chunks: dict[str, ChunkData] | None = Field(default=None, description="Chunks for facts, keyed by chunk_id")
+    source_facts: dict[str, RecallResult] | None = Field(
+        default=None, description="Source facts for observation-type results, keyed by fact ID"
+    )


 class EntityInput(BaseModel):
@@ -413,7 +429,6 @@ class RetainRequest(BaseModel):
                    },
                ],
                "async": False,
-                "document_tags": ["user_a", "user_b"],
            }
        }
    )
@@ -426,7 +441,8 @@ class RetainRequest(BaseModel):
    )
    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.",
+        description="Deprecated. Use item-level tags instead.",
+        deprecated=True,
    )


@@ -1959,6 +1975,10 @@ 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

+            # Determine source facts inclusion settings
+            include_source_facts = request.include.source_facts is not None
+            max_source_facts_tokens = request.include.source_facts.max_tokens if include_source_facts else 4096
+
            pre_recall = time.time() - handler_start
            # Run recall with tracing (record metrics)
            with metrics.record_operation(
@@ -1977,14 +1997,16 @@ def _register_routes(app: FastAPI):
                    max_entity_tokens=max_entity_tokens,
                    include_chunks=include_chunks,
                    max_chunk_tokens=max_chunk_tokens,
+                    include_source_facts=include_source_facts,
+                    max_source_facts_tokens=max_source_facts_tokens,
                    request_context=request_context,
                    tags=request.tags,
                    tags_match=request.tags_match,
                )

            # Convert core MemoryFact objects to API RecallResult objects (excluding internal metrics)
-            recall_results = [
-                RecallResult(
+            def _fact_to_result(fact: "MemoryFact") -> RecallResult:
+                return RecallResult(
                    id=fact.id,
                    text=fact.text,
                    type=fact.fact_type,
@@ -1996,9 +2018,10 @@ def _register_routes(app: FastAPI):
                    document_id=fact.document_id,
                    chunk_id=fact.chunk_id,
                    tags=fact.tags,
+                    source_fact_ids=fact.source_fact_ids,
                )
-                for fact in core_result.results
-            ]
+
+            recall_results = [_fact_to_result(fact) for fact in core_result.results]

            # Convert chunks from engine to HTTP API format
            chunks_response = None
@@ -2026,11 +2049,19 @@ def _register_routes(app: FastAPI):
                        ],
                    )

+            # Convert source facts dict to API format
+            source_facts_response = None
+            if core_result.source_facts:
+                source_facts_response = {
+                    fact_id: _fact_to_result(fact) for fact_id, fact in core_result.source_facts.items()
+                }
+
            response = RecallResponse(
                results=recall_results,
                trace=core_result.trace,
                entities=entities_response,
                chunks=chunks_response,
+                source_facts=source_facts_response,
            )

            handler_duration = time.time() - handler_start
@@ -78,10 +78,9 @@ def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
                   If False, only expose bank-scoped tools without bank_id parameters.

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

    # Configure and register tools using shared module
    config = MCPToolsConfig(
@@ -211,9 +210,9 @@ class MCPMiddleware:
        else:
            # Create servers internally (for direct construction / tests)
            self.multi_bank_server = create_mcp_server(memory, multi_bank=True)
-            self.multi_bank_app = self.multi_bank_server.http_app(path="/")
+            self.multi_bank_app = self.multi_bank_server.http_app(path="/", stateless_http=True)
            self.single_bank_server = create_mcp_server(memory, multi_bank=False)
-            self.single_bank_app = self.single_bank_server.http_app(path="/")
+            self.single_bank_app = self.single_bank_server.http_app(path="/", stateless_http=True)

    def _get_header(self, scope: dict, name: str) -> str | None:
        """Extract a header value from ASGI scope."""
@@ -379,9 +378,9 @@ def create_mcp_servers(memory: MemoryEngine):
        Tuple of (multi_bank_server, single_bank_server, multi_bank_app, single_bank_app)
    """
    multi_bank_server = create_mcp_server(memory, multi_bank=True)
-    multi_bank_app = multi_bank_server.http_app(path="/")
+    multi_bank_app = multi_bank_server.http_app(path="/", stateless_http=True)

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

    return multi_bank_server, single_bank_server, multi_bank_app, single_bank_app
@@ -233,8 +233,6 @@ ENV_GRAPH_RETRIEVER = "HINDSIGHT_API_GRAPH_RETRIEVER"
 ENV_MPFP_TOP_K_NEIGHBORS = "HINDSIGHT_API_MPFP_TOP_K_NEIGHBORS"
 ENV_RECALL_MAX_CONCURRENT = "HINDSIGHT_API_RECALL_MAX_CONCURRENT"
 ENV_RECALL_CONNECTION_BUDGET = "HINDSIGHT_API_RECALL_CONNECTION_BUDGET"
-ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
-ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 ENV_MENTAL_MODEL_REFRESH_CONCURRENCY = "HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY"

 # OpenTelemetry tracing configuration
@@ -272,6 +270,8 @@ ENV_FILE_STORAGE_AZURE_CONTAINER = "HINDSIGHT_API_FILE_STORAGE_AZURE_CONTAINER"
 ENV_FILE_STORAGE_AZURE_ACCOUNT_NAME = "HINDSIGHT_API_FILE_STORAGE_AZURE_ACCOUNT_NAME"
 ENV_FILE_STORAGE_AZURE_ACCOUNT_KEY = "HINDSIGHT_API_FILE_STORAGE_AZURE_ACCOUNT_KEY"
 ENV_FILE_PARSER = "HINDSIGHT_API_FILE_PARSER"
+ENV_FILE_PARSER_IRIS_TOKEN = "HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN"
+ENV_FILE_PARSER_IRIS_ORG_ID = "HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID"
 ENV_FILE_CONVERSION_MAX_BATCH_SIZE_MB = "HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE_MB"
 ENV_FILE_CONVERSION_MAX_BATCH_SIZE = "HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE"
 ENV_ENABLE_FILE_UPLOAD_API = "HINDSIGHT_API_ENABLE_FILE_UPLOAD_API"
@@ -314,7 +314,7 @@ DEFAULT_LLM_PROVIDER = "openai"

 # Provider-specific default models
 PROVIDER_DEFAULT_MODELS = {
-    "openai": "o3-mini",
+    "openai": "gpt-4o-mini",
    "anthropic": "claude-haiku-4-5-20251001",
    "gemini": "gemini-2.5-flash",
    "groq": "openai/gpt-oss-120b",
@@ -325,7 +325,7 @@ PROVIDER_DEFAULT_MODELS = {
    "claude-code": "claude-sonnet-4-5-20250929",
    "mock": "mock-model",
 }
-DEFAULT_LLM_MODEL = "o3-mini"  # Fallback if provider not in table
+DEFAULT_LLM_MODEL = "gpt-4o-mini"  # Fallback if provider not in table
 DEFAULT_LLM_MAX_CONCURRENT = 32
 DEFAULT_LLM_MAX_RETRIES = 10  # Max retry attempts for LLM API calls
 DEFAULT_LLM_INITIAL_BACKOFF = 1.0  # Initial backoff in seconds for retry exponential backoff
@@ -387,7 +387,6 @@ DEFAULT_GRAPH_RETRIEVER = "link_expansion"  # Options: "link_expansion", "mpfp",
 DEFAULT_MPFP_TOP_K_NEIGHBORS = 20  # Fan-out limit per node in MPFP graph traversal
 DEFAULT_RECALL_MAX_CONCURRENT = 32  # Max concurrent recall operations per worker
 DEFAULT_RECALL_CONNECTION_BUDGET = 4  # Max concurrent DB connections per recall operation
-DEFAULT_MCP_LOCAL_BANK_ID = "mcp"
 DEFAULT_MENTAL_MODEL_REFRESH_CONCURRENCY = 8  # Max concurrent mental model refreshes

 # Retain settings
@@ -645,7 +644,9 @@ class HindsightConfig:
    file_storage_azure_container: str | None  # Azure container name (required for azure storage)
    file_storage_azure_account_name: str | None  # Azure storage account name
    file_storage_azure_account_key: str | None  # Azure storage account key
-    file_parser: str  # File parser to use (e.g., "markitdown")
+    file_parser: str  # File parser to use (e.g., "markitdown", "iris")
+    file_parser_iris_token: str | None  # Vectorize API token for iris parser (VECTORIZE_TOKEN)
+    file_parser_iris_org_id: str | None  # Vectorize org ID for iris parser (VECTORIZE_ORG_ID)
    file_conversion_max_batch_size_mb: int  # Max total batch size in MB (all files combined)
    file_conversion_max_batch_size: int  # Max files per request
    enable_file_upload_api: bool
@@ -712,6 +713,8 @@ class HindsightConfig:
        "file_storage_s3_secret_access_key",
        "file_storage_gcs_service_account_key",
        "file_storage_azure_account_key",
+        # File parser credentials
+        "file_parser_iris_token",
    }

    # CONFIGURABLE_FIELDS: Safe behavioral settings that can be customized per-tenant/bank
@@ -1030,6 +1033,8 @@ class HindsightConfig:
            file_storage_azure_account_name=os.getenv(ENV_FILE_STORAGE_AZURE_ACCOUNT_NAME) or None,
            file_storage_azure_account_key=os.getenv(ENV_FILE_STORAGE_AZURE_ACCOUNT_KEY) or None,
            file_parser=os.getenv(ENV_FILE_PARSER, DEFAULT_FILE_PARSER),
+            file_parser_iris_token=os.getenv(ENV_FILE_PARSER_IRIS_TOKEN) or None,
+            file_parser_iris_org_id=os.getenv(ENV_FILE_PARSER_IRIS_ORG_ID) or None,
            file_conversion_max_batch_size_mb=int(
                os.getenv(ENV_FILE_CONVERSION_MAX_BATCH_SIZE_MB, str(DEFAULT_FILE_CONVERSION_MAX_BATCH_SIZE_MB))
            ),
@@ -1374,7 +1374,7 @@ class MemoryEngine(MemoryEngineInterface):
        logger.debug(f"File storage initialized ({config.file_storage_type})")

        # Initialize parser registry
-        from .parsers import FileParserRegistry, MarkitdownParser
+        from .parsers import FileParserRegistry, IrisParser, MarkitdownParser

        self._parser_registry = FileParserRegistry()
        try:
@@ -1382,6 +1382,13 @@ class MemoryEngine(MemoryEngineInterface):
            logger.debug("Registered markitdown parser")
        except ImportError:
            logger.warning("markitdown not available - file parsing disabled")
+        iris_token = config.file_parser_iris_token
+        iris_org_id = config.file_parser_iris_org_id
+        if iris_token and iris_org_id:
+            self._parser_registry.register(IrisParser(token=iris_token, org_id=iris_org_id))
+            logger.debug("Registered iris parser")
+        else:
+            logger.debug("Iris parser not registered (VECTORIZE_TOKEN or VECTORIZE_ORG_ID not set)")

        # Set executor for task backend and initialize
        self._task_backend.set_executor(self.execute_task)
@@ -2013,6 +2020,8 @@ class MemoryEngine(MemoryEngineInterface):
        max_entity_tokens: int = 500,
        include_chunks: bool = False,
        max_chunk_tokens: int = 8192,
+        include_source_facts: bool = False,
+        max_source_facts_tokens: int = 4096,
        request_context: "RequestContext",
        tags: list[str] | None = None,
        tags_match: TagsMatch = "any",
@@ -2152,6 +2161,8 @@ class MemoryEngine(MemoryEngineInterface):
                            tags_match=tags_match,
                            connection_budget=_connection_budget,
                            quiet=_quiet,
+                            include_source_facts=include_source_facts,
+                            max_source_facts_tokens=max_source_facts_tokens,
                        )
                        break  # Success - exit retry loop
                    except Exception as e:
@@ -2276,6 +2287,8 @@ class MemoryEngine(MemoryEngineInterface):
        tags_match: TagsMatch = "any",
        connection_budget: int | None = None,
        quiet: bool = False,
+        include_source_facts: bool = False,
+        max_source_facts_tokens: int = 4096,
    ) -> RecallResultModel:
        """
        Search implementation with modular retrieval and reranking.
@@ -2621,6 +2634,8 @@ class MemoryEngine(MemoryEngineInterface):
            rerank_span.set_attribute("hindsight.bank_id", bank_id)
            rerank_span.set_attribute("hindsight.candidates_count", len(merged_candidates))

+            scored_results: list = []
+            pre_filtered_count = 0
            try:
                # Ensure reranker is initialized (for lazy initialization mode)
                await reranker_instance.ensure_initialized()
@@ -2628,7 +2643,6 @@ class MemoryEngine(MemoryEngineInterface):
                # Pre-filter candidates to reduce reranking cost (RRF already provides good ranking)
                # This is especially important for remote rerankers with network latency
                reranker_max_candidates = get_config().reranker_max_candidates
-                pre_filtered_count = 0
                if len(merged_candidates) > reranker_max_candidates:
                    # Sort by RRF score and take top candidates
                    merged_candidates.sort(key=lambda mc: mc.rrf_score, reverse=True)
@@ -2871,15 +2885,112 @@ class MemoryEngine(MemoryEngineInterface):
                    )
                top_results_dicts.append(result_dict)

+            # Fetch source facts for observation-type results (mirrors chunks pattern)
+            source_fact_ids_by_obs: dict[str, list[str]] = {}  # obs_id -> [source_id, ...]
+            source_facts_dict: dict[str, MemoryFact] | None = None
+            if include_source_facts:
+                observation_ids = [uuid.UUID(sr.id) for sr in top_scored if sr.retrieval.fact_type == "observation"]
+                if observation_ids:
+                    async with acquire_with_retry(pool) as sf_conn:
+                        # Fetch source_memory_ids for all observation results
+                        obs_rows = await sf_conn.fetch(
+                            f"""
+                            SELECT id, source_memory_ids
+                            FROM {fq_table("memory_units")}
+                            WHERE id = ANY($1::uuid[]) AND fact_type = 'observation'
+                            """,
+                            observation_ids,
+                        )
+
+                        # Collect unique source IDs in order of first appearance
+                        seen_source_ids: set[str] = set()
+                        source_ids_ordered: list[str] = []
+                        for obs_row in obs_rows:
+                            obs_id = str(obs_row["id"])
+                            sids = [str(s) for s in (obs_row["source_memory_ids"] or [])]
+                            source_fact_ids_by_obs[obs_id] = sids
+                            for sid in sids:
+                                if sid not in seen_source_ids:
+                                    source_ids_ordered.append(sid)
+                                    seen_source_ids.add(sid)
+
+                        # Fetch source fact content up to token budget
+                        if source_ids_ordered:
+                            import uuid as uuid_module
+
+                            source_rows = await sf_conn.fetch(
+                                f"""
+                                SELECT id, text, fact_type, context, occurred_start, occurred_end,
+                                       mentioned_at, document_id, chunk_id, tags
+                                FROM {fq_table("memory_units")}
+                                WHERE id = ANY($1::uuid[])
+                                """,
+                                [uuid_module.UUID(sid) for sid in source_ids_ordered],
+                            )
+                            source_row_by_id = {str(r["id"]): r for r in source_rows}
+
+                            encoding = _get_tiktoken_encoding()
+                            source_facts_dict = {}
+                            total_source_tokens = 0
+                            for sid in source_ids_ordered:
+                                if sid not in source_row_by_id:
+                                    continue
+                                r = source_row_by_id[sid]
+                                fact_tokens = len(encoding.encode(r["text"]))
+                                if total_source_tokens + fact_tokens > max_source_facts_tokens:
+                                    break
+                                source_facts_dict[sid] = MemoryFact(
+                                    id=sid,
+                                    text=r["text"],
+                                    fact_type=r["fact_type"],
+                                    context=r["context"],
+                                    occurred_start=r["occurred_start"].isoformat() if r["occurred_start"] else None,
+                                    occurred_end=r["occurred_end"].isoformat() if r["occurred_end"] else None,
+                                    mentioned_at=r["mentioned_at"].isoformat() if r["mentioned_at"] else None,
+                                    document_id=r["document_id"],
+                                    chunk_id=str(r["chunk_id"]) if r["chunk_id"] else None,
+                                    tags=r["tags"] or None,
+                                )
+                                total_source_tokens += fact_tokens
+
+            # Get entities for each fact if include_entities is requested
+            fact_entity_map = {}  # unit_id -> list of (entity_id, entity_name)
+            if include_entities and top_scored:
+                unit_ids = [uuid.UUID(sr.id) for sr in top_scored]
+                if unit_ids:
+                    async with acquire_with_retry(pool) as entity_conn:
+                        entity_rows = await entity_conn.fetch(
+                            f"""
+                            SELECT ue.unit_id, e.id as entity_id, e.canonical_name
+                            FROM {fq_table("unit_entities")} ue
+                            JOIN {fq_table("entities")} e ON ue.entity_id = e.id
+                            WHERE ue.unit_id = ANY($1::uuid[])
+                            """,
+                            unit_ids,
+                        )
+                        for row in entity_rows:
+                            unit_id = str(row["unit_id"])
+                            if unit_id not in fact_entity_map:
+                                fact_entity_map[unit_id] = []
+                            fact_entity_map[unit_id].append(
+                                {"entity_id": str(row["entity_id"]), "canonical_name": row["canonical_name"]}
+                            )
+
            # Convert results to MemoryFact objects
            memory_facts = []
            for result_dict in top_results_dicts:
+                result_id = str(result_dict.get("id"))
+                # Get entity names for this fact
+                entity_names = None
+                if include_entities and result_id in fact_entity_map:
+                    entity_names = [e["canonical_name"] for e in fact_entity_map[result_id]]
+
                memory_facts.append(
                    MemoryFact(
-                        id=str(result_dict.get("id")),
+                        id=result_id,
                        text=result_dict.get("text"),
                        fact_type=result_dict.get("fact_type", "world"),
-                        entities=None,  # Entity observations removed
+                        entities=entity_names,
                        context=result_dict.get("context"),
                        occurred_start=result_dict.get("occurred_start"),
                        occurred_end=result_dict.get("occurred_end"),
@@ -2887,11 +2998,36 @@ class MemoryEngine(MemoryEngineInterface):
                        document_id=result_dict.get("document_id"),
                        chunk_id=result_dict.get("chunk_id"),
                        tags=result_dict.get("tags"),
+                        source_fact_ids=source_fact_ids_by_obs.get(result_id) if include_source_facts else None,
                    )
                )

-            # Entity observations removed - always set to None
+            # Fetch entity observations if requested
            entities_dict = None
+            total_entity_tokens = 0
+            if include_entities and fact_entity_map:
+                # Collect unique entities in order of fact relevance (preserving order from top_scored)
+                entities_ordered = []  # list of (entity_id, entity_name) tuples
+                seen_entity_ids = set()
+
+                for sr in top_scored:
+                    unit_id = sr.id
+                    if unit_id in fact_entity_map:
+                        for entity in fact_entity_map[unit_id]:
+                            entity_id = entity["entity_id"]
+                            entity_name = entity["canonical_name"]
+                            if entity_id not in seen_entity_ids:
+                                entities_ordered.append((entity_id, entity_name))
+                                seen_entity_ids.add(entity_id)
+
+                # Return entities with empty observations (summaries now live in mental models)
+                entities_dict = {}
+                for entity_id, entity_name in entities_ordered:
+                    entities_dict[entity_name] = EntityState(
+                        entity_id=entity_id,
+                        canonical_name=entity_name,
+                        observations=[],  # Mental models provide this now
+                    )

            # Finalize trace if enabled
            trace_dict = None
@@ -2902,6 +3038,7 @@ class MemoryEngine(MemoryEngineInterface):
            # Log final recall stats
            total_time = time.time() - recall_start
            num_chunks = len(chunks_dict) if chunks_dict else 0
+            num_entities = len(entities_dict) if entities_dict else 0
            # Include wait times in log if significant
            wait_parts = []
            if semaphore_wait > 0.01:
@@ -2910,12 +3047,18 @@ class MemoryEngine(MemoryEngineInterface):
                wait_parts.append(f"conn={max_conn_wait:.3f}s")
            wait_info = f" | waits: {', '.join(wait_parts)}" if wait_parts else ""
            log_buffer.append(
-                f"[RECALL {recall_id}] Complete: {len(top_scored)} facts ({total_tokens} tok), {num_chunks} chunks ({total_chunk_tokens} tok) | {fact_type_summary} | {total_time:.3f}s{wait_info}"
+                f"[RECALL {recall_id}] Complete: {len(top_scored)} facts ({total_tokens} tok), {num_chunks} chunks ({total_chunk_tokens} tok), {num_entities} entities ({total_entity_tokens} tok) | {fact_type_summary} | {total_time:.3f}s{wait_info}"
            )
            if not quiet:
                logger.info("\n" + "\n".join(log_buffer))

-            return RecallResultModel(results=memory_facts, trace=trace_dict, entities=entities_dict, chunks=chunks_dict)
+            return RecallResultModel(
+                results=memory_facts,
+                trace=trace_dict,
+                entities=entities_dict,
+                chunks=chunks_dict,
+                source_facts=source_facts_dict,
+            )

        except Exception as e:
            log_buffer.append(f"[RECALL {recall_id}] ERROR after {time.time() - recall_start:.3f}s: {str(e)}")
@@ -1,9 +1,10 @@
 """File parser implementations."""

-from .base import FileParser
+from .base import FileParser, UnsupportedFileTypeError
+from .iris import IrisParser
 from .markitdown import MarkitdownParser

-__all__ = ["FileParser", "MarkitdownParser", "FileParserRegistry"]
+__all__ = ["FileParser", "UnsupportedFileTypeError", "IrisParser", "MarkitdownParser", "FileParserRegistry"]


 class FileParserRegistry:
@@ -43,7 +44,8 @@ class FileParserRegistry:
            ValueError: If no suitable parser found
        """
        if name:
-            # Explicit parser requested
+            # Explicit parser requested — return it directly, let the parser
+            # raise UnsupportedFileTypeError from convert() if needed
            if name not in self._parsers:
                raise ValueError(f"Parser '{name}' not found. Available: {list(self._parsers.keys())}")
            return self._parsers[name]
@@ -3,6 +3,12 @@
 from abc import ABC, abstractmethod


+class UnsupportedFileTypeError(Exception):
+    """Raised by a parser when it does not support the given file type."""
+
+    pass
+
+
 class FileParser(ABC):
    """Abstract base for file to markdown parsers."""

@@ -19,24 +25,27 @@ class FileParser(ABC):
            Markdown content as string

        Raises:
-            ValueError: If file format is not supported
-            RuntimeError: If parsing fails
+            UnsupportedFileTypeError: If the file type is not supported by this parser
+            RuntimeError: If parsing fails for another reason
        """
        pass

-    @abstractmethod
    def supports(self, filename: str, content_type: str | None = None) -> bool:
        """
        Check if parser supports this file type.

+        Override this for local/static extension-based filtering.
+        Parsers that delegate to a remote service should leave this as True
+        and raise UnsupportedFileTypeError from convert() instead.
+
        Args:
            filename: File name (used for extension check)
            content_type: MIME type (optional)

        Returns:
-            True if this parser can handle the file
+            True if this parser can handle the file (default: True)
        """
-        pass
+        return True

    @abstractmethod
    def name(self) -> str:
@@ -0,0 +1,137 @@
+"""Iris parser implementation using the Vectorize Iris HTTP API."""
+
+import asyncio
+import logging
+import mimetypes
+import time
+
+import httpx
+
+from .base import FileParser, UnsupportedFileTypeError
+
+logger = logging.getLogger(__name__)
+
+_IRIS_BASE_URL = "https://api.vectorize.io/v1"
+_DEFAULT_POLL_INTERVAL = 2.0  # seconds
+_DEFAULT_TIMEOUT = 300.0  # seconds
+
+
+class IrisParser(FileParser):
+    """
+    Iris file parser using the Vectorize Iris cloud extraction service.
+
+    Uploads files to the Vectorize Iris API, starts an extraction job,
+    and polls until the text is ready. The API determines which file types
+    are supported — UnsupportedFileTypeError is raised if the file is rejected.
+
+    Authentication:
+        Requires HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN and
+        HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID environment variables,
+        or pass them explicitly via the constructor.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        org_id: str,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ):
+        """
+        Initialize iris parser.
+
+        Args:
+            token: Vectorize API token
+            org_id: Vectorize organization ID
+            poll_interval: Seconds between status poll requests (default: 2)
+            timeout: Maximum seconds to wait for extraction (default: 300)
+        """
+        self._token = token
+        self._org_id = org_id
+        self._poll_interval = poll_interval
+        self._timeout = timeout
+        self._auth_headers = {"Authorization": f"Bearer {token}"}
+
+    async def convert(self, file_data: bytes, filename: str) -> str:
+        """
+        Parse file to text using the Vectorize Iris API.
+
+        Raises:
+            UnsupportedFileTypeError: If the Iris API rejects the file type (4xx)
+            RuntimeError: If extraction fails for another reason
+        """
+        content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+        async with httpx.AsyncClient() as client:
+            # Step 1: Request a presigned upload URL
+            init_resp = await client.post(
+                f"{_IRIS_BASE_URL}/org/{self._org_id}/files",
+                headers=self._auth_headers,
+                json={"name": filename, "contentType": content_type},
+            )
+            _raise_for_status(init_resp, filename, "file upload init")
+            init_data = init_resp.json()
+            file_id: str = init_data["fileId"]
+            upload_url: str = init_data["uploadUrl"]
+
+            # Step 2: Upload the file bytes to the presigned URL (no auth header)
+            upload_resp = await client.put(
+                upload_url,
+                content=file_data,
+                headers={"Content-Type": content_type},
+            )
+            _raise_for_status(upload_resp, filename, "file upload")
+
+            # Step 3: Start extraction
+            extract_resp = await client.post(
+                f"{_IRIS_BASE_URL}/org/{self._org_id}/extraction",
+                headers=self._auth_headers,
+                json={"fileId": file_id},
+            )
+            _raise_for_status(extract_resp, filename, "start extraction")
+            extraction_id: str = extract_resp.json()["extractionId"]
+
+            # Step 4: Poll until ready or timeout
+            deadline = time.monotonic() + self._timeout
+            while True:
+                status_resp = await client.get(
+                    f"{_IRIS_BASE_URL}/org/{self._org_id}/extraction/{extraction_id}",
+                    headers=self._auth_headers,
+                )
+                _raise_for_status(status_resp, filename, "poll extraction status")
+                status_data = status_resp.json()
+
+                if status_data.get("ready"):
+                    data = status_data.get("data", {})
+                    if not data.get("success"):
+                        error = data.get("error", "unknown error")
+                        raise RuntimeError(f"Iris extraction failed for '{filename}': {error}")
+                    text = data.get("text")
+                    if not text:
+                        raise RuntimeError(f"No content extracted from '{filename}'")
+                    return text
+
+                if time.monotonic() >= deadline:
+                    raise RuntimeError(f"Iris extraction timed out after {self._timeout}s for '{filename}'")
+
+                await asyncio.sleep(self._poll_interval)
+
+    def name(self) -> str:
+        """Get parser name."""
+        return "iris"
+
+
+def _raise_for_status(response: httpx.Response, filename: str, step: str) -> None:
+    """
+    Raise an appropriate error including the response body on HTTP errors.
+
+    Raises UnsupportedFileTypeError for 4xx responses (file rejected by the API),
+    RuntimeError for other HTTP errors.
+    """
+    if not response.is_error:
+        return
+    body = response.text or "<empty>"
+    msg = f"Iris API error during {step} for '{filename}': {response.status_code} {response.reason_phrase} — {body}"
+    if response.is_client_error:
+        raise UnsupportedFileTypeError(msg)
+    raise RuntimeError(msg)
@@ -159,6 +159,10 @@ class MemoryFact(BaseModel):
        None, description="ID of the chunk this fact was extracted from (format: bank_id_document_id_chunk_index)"
    )
    tags: list[str] | None = Field(None, description="Visibility scope tags associated with this fact")
+    source_fact_ids: list[str] | None = Field(
+        None,
+        description="IDs of source facts this observation was derived from (observation type only, when source_facts is enabled)",
+    )


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


 class ReflectResult(BaseModel):
@@ -1274,8 +1274,8 @@ from .types import ExtractedFact as ExtractedFactType

 logger = logging.getLogger(__name__)

-# Each fact gets 10 seconds offset to preserve ordering within a document
-SECONDS_PER_FACT = 10
+# Each fact gets 10ms offset to preserve ordering within a document
+SECONDS_PER_FACT = 0.01


 async def extract_facts_from_contents_batch_api(
@@ -156,13 +156,22 @@ async def retain_batch(
    )

    if not extracted_facts:
-        # Still need to create document if document_id was provided
+        # Still need to create document if document_id was provided or chunks exist
+        from collections import defaultdict
+
+        docs_tracked = 0
        async with acquire_with_retry(pool) as conn:
            async with conn.transaction():
                await fact_storage.ensure_bank_exists(conn, bank_id)

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

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

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

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

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

@@ -262,6 +262,8 @@ def main():
            file_storage_azure_account_name=config.file_storage_azure_account_name,
            file_storage_azure_account_key=config.file_storage_azure_account_key,
            file_parser=config.file_parser,
+            file_parser_iris_token=config.file_parser_iris_token,
+            file_parser_iris_org_id=config.file_parser_iris_org_id,
            file_conversion_max_batch_size_mb=config.file_conversion_max_batch_size_mb,
            file_conversion_max_batch_size=config.file_conversion_max_batch_size,
            enable_file_upload_api=config.enable_file_upload_api,
@@ -1,8 +1,14 @@
 """
-Local MCP server for use with Claude Code (stdio transport).
+Local MCP server entry point for use with Claude Code (HTTP transport).

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

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

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

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


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

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

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


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

 [project]
 name = "hindsight-api"
-version = "0.4.11"
+version = "0.4.13"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -2,9 +2,13 @@
 Tests for document tracking and upsert functionality.
 """
 import logging
-import pytest
 from datetime import datetime, timezone
+from unittest.mock import patch
+
+import pytest
+
 from hindsight_api import RequestContext
+from hindsight_api.engine.response_models import TokenUsage


@pytest.mark.asyncio
@@ -311,3 +315,52 @@ async def test_document_persisted_with_zero_facts_async_submit(memory, request_c

    finally:
        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_document_stored_without_chunks_when_zero_facts(memory_no_llm_verify, request_context):
+    """
+    Regression test: when 0 facts are extracted from chunked content, the document row
+    must be stored but no chunk rows should be written.
+    """
+    bank_id = f"test_zero_facts_no_chunks_{datetime.now(timezone.utc).timestamp()}"
+    document_id = "doc-zero-facts-chunked"
+
+    # Content large enough to exceed default retain_chunk_size (3000 chars) so chunking is triggered
+    content = "Alice works at Google. " * 200  # ~4600 chars
+
+    async def mock_llm_zero_facts(*args, **kwargs):
+        response = {"facts": []}
+        if kwargs.get("return_usage", False):
+            return response, TokenUsage(input_tokens=10, output_tokens=2)
+        return response
+
+    try:
+        with patch("hindsight_api.engine.llm_wrapper.LLMProvider.call", new=mock_llm_zero_facts):
+            units = await memory_no_llm_verify.retain_async(
+                bank_id=bank_id,
+                content=content,
+                document_id=document_id,
+                request_context=request_context,
+            )
+
+        assert units == [], "Should return no memory units when LLM extracts zero facts"
+
+        # Document row must exist
+        doc = await memory_no_llm_verify.get_document(document_id, bank_id, request_context=request_context)
+        assert doc is not None, "Document row must be stored even when zero facts are extracted"
+        assert doc["id"] == document_id
+        assert doc["memory_unit_count"] == 0
+
+        # No chunk rows should be stored
+        pool = await memory_no_llm_verify._get_pool()
+        async with pool.acquire() as conn:
+            chunk_count = await conn.fetchval(
+                "SELECT COUNT(*) FROM chunks WHERE document_id = $1 AND bank_id = $2",
+                document_id,
+                bank_id,
+            )
+        assert chunk_count == 0, "No chunk rows should be stored when zero facts are extracted"
+
+    finally:
+        await memory_no_llm_verify.delete_bank(bank_id, request_context=request_context)
@@ -0,0 +1,72 @@
+"""
+Integration tests for the Iris file parser.
+
+Tests are skipped automatically if HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN
+and HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID are not set in the environment.
+"""
+
+import os
+
+import pytest
+
+from hindsight_api.config import ENV_FILE_PARSER_IRIS_ORG_ID, ENV_FILE_PARSER_IRIS_TOKEN
+from hindsight_api.engine.parsers.iris import IrisParser
+
+_token = os.getenv(ENV_FILE_PARSER_IRIS_TOKEN)
+_org_id = os.getenv(ENV_FILE_PARSER_IRIS_ORG_ID)
+
+pytestmark = pytest.mark.skipif(
+    not (_token and _org_id),
+    reason="HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN and HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID not set",
+)
+
+# Minimal valid PDF with the text "Hello from Hindsight"
+_SAMPLE_PDF = b"""%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R] /Count 1 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792]
+   /Contents 4 0 R /Resources << /Font << /F1 << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >> >> >> >>
+endobj
+4 0 obj
+<< /Length 44 >>
+stream
+BT /F1 12 Tf 100 700 Td (Hello from Hindsight) Tj ET
+endstream
+endobj
+xref
+0 5
+0000000000 65535 f
+0000000009 00000 n
+0000000058 00000 n
+0000000115 00000 n
+0000000274 00000 n
+trailer << /Size 5 /Root 1 0 R >>
+startxref
+369
+%%EOF"""
+
+
+@pytest.fixture
+def iris_parser() -> IrisParser:
+    return IrisParser(token=_token, org_id=_org_id)
+
+
+@pytest.mark.asyncio
+async def test_iris_parser_converts_pdf(iris_parser: IrisParser):
+    """IrisParser should extract text from a valid PDF."""
+    result = await iris_parser.convert(_SAMPLE_PDF, "sample.pdf")
+    assert isinstance(result, str)
+    assert len(result) > 0
+
+
+@pytest.mark.asyncio
+async def test_iris_parser_name(iris_parser: IrisParser):
+    """IrisParser.name() should return 'iris'."""
+    assert iris_parser.name() == "iris"
+
+
@@ -1,212 +0,0 @@
-"""Test local MCP server."""
-
-import asyncio
-import pytest
-from unittest.mock import AsyncMock, MagicMock
-
-
-@pytest.fixture
-def mock_memory():
-    """Create a mock MemoryEngine."""
-    memory = MagicMock()
-    memory._initialized = True
-    memory.retain_batch_async = AsyncMock()
-    memory.recall_async = AsyncMock(return_value=MagicMock(results=[]))
-    return memory
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain(mock_memory):
-    """Test that retain tool fires async and returns immediately."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    bank_id = "test-bank"
-    mcp_server = create_local_mcp_server(bank_id, memory=mock_memory)
-
-    # Get the tools
-    tools = mcp_server._tool_manager._tools
-    assert "retain" in tools
-
-    # Call retain
-    retain_tool = tools["retain"]
-    result = await retain_tool.fn(content="test content", context="test_context")
-
-    # Returns immediately with accepted status
-    assert result["status"] == "accepted"
-
-    # Wait for background task to complete
-    await asyncio.sleep(0.1)
-
-    # Verify the memory was called correctly
-    mock_memory.retain_batch_async.assert_called_once()
-    call_kwargs = mock_memory.retain_batch_async.call_args.kwargs
-    assert call_kwargs["bank_id"] == "test-bank"
-    assert call_kwargs["contents"] == [{"content": "test content", "context": "test_context"}]
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_recall(mock_memory):
-    """Test that recall tool calls memory.recall_async with correct params."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-    from hindsight_api.engine.memory_engine import Budget
-
-    # Mock recall_async to return a proper pydantic model
-    mock_result = MagicMock()
-    mock_result.model_dump.return_value = {"results": []}
-    mock_memory.recall_async = AsyncMock(return_value=mock_result)
-
-    bank_id = "test-bank"
-    mcp_server = create_local_mcp_server(bank_id, memory=mock_memory)
-
-    # Get the tools
-    tools = mcp_server._tool_manager._tools
-    assert "recall" in tools
-
-    # Call recall
-    recall_tool = tools["recall"]
-    result = await recall_tool.fn(query="test query", max_tokens=2048)
-
-    # Result is a dict
-    assert isinstance(result, dict)
-
-    # Verify the memory was called correctly
-    mock_memory.recall_async.assert_called_once()
-    call_kwargs = mock_memory.recall_async.call_args.kwargs
-    assert call_kwargs["bank_id"] == "test-bank"
-    assert call_kwargs["query"] == "test query"
-    assert call_kwargs["max_tokens"] == 2048
-    assert call_kwargs["budget"] == Budget.HIGH
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain_with_default_context(mock_memory):
-    """Test that retain uses default context when not provided."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    bank_id = "test-bank"
-    mcp_server = create_local_mcp_server(bank_id, memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    retain_tool = tools["retain"]
-
-    # Call retain without context
-    await retain_tool.fn(content="test content")
-
-    # Wait for background task
-    await asyncio.sleep(0.1)
-
-    call_kwargs = mock_memory.retain_batch_async.call_args.kwargs
-    assert call_kwargs["contents"] == [{"content": "test content", "context": "general"}]
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain_error_handling(mock_memory):
-    """Test that retain errors are logged but don't affect response."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    mock_memory.retain_batch_async = AsyncMock(side_effect=Exception("Test error"))
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    retain_tool = tools["retain"]
-
-    # Retain returns immediately with accepted status (fire and forget)
-    result = await retain_tool.fn(content="test content")
-    assert result["status"] == "accepted"
-
-    # Wait for background task to complete (and log error)
-    await asyncio.sleep(0.1)
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_recall_error_handling(mock_memory):
-    """Test that recall handles errors gracefully."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    mock_memory.recall_async = AsyncMock(side_effect=Exception("Test error"))
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    recall_tool = tools["recall"]
-
-    result = await recall_tool.fn(query="test query")
-
-    # Result is a dict with error
-    assert isinstance(result, dict)
-    assert "error" in result
-    assert result["results"] == []
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_recall_with_defaults(mock_memory):
-    """Test that recall uses default max_tokens and HIGH budget."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-    from hindsight_api.engine.memory_engine import Budget
-
-    mock_result = MagicMock()
-    mock_result.model_dump.return_value = {"results": []}
-    mock_memory.recall_async = AsyncMock(return_value=mock_result)
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    recall_tool = tools["recall"]
-
-    # Call with defaults
-    await recall_tool.fn(query="test query")
-
-    call_kwargs = mock_memory.recall_async.call_args.kwargs
-    assert call_kwargs["max_tokens"] == 4096
-    assert call_kwargs["budget"] == Budget.HIGH
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain_with_timestamp(mock_memory):
-    """Test that retain passes timestamp as event_date."""
-    from datetime import datetime, timezone
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    retain_tool = tools["retain"]
-
-    # Call retain with timestamp
-    result = await retain_tool.fn(
-        content="test content", context="test_context", timestamp="2024-01-15T10:30:00Z"
-    )
-
-    assert result["status"] == "accepted"
-
-    # Wait for background task
-    await asyncio.sleep(0.1)
-
-    call_kwargs = mock_memory.retain_batch_async.call_args.kwargs
-    contents = call_kwargs["contents"]
-    assert len(contents) == 1
-    assert contents[0]["content"] == "test content"
-    assert contents[0]["context"] == "test_context"
-    assert "event_date" in contents[0]
-    assert contents[0]["event_date"] == datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc)
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain_with_invalid_timestamp(mock_memory):
-    """Test that retain rejects invalid timestamp format."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    retain_tool = tools["retain"]
-
-    # Call retain with invalid timestamp
-    result = await retain_tool.fn(content="test content", timestamp="not-a-date")
-
-    assert result["status"] == "error"
-    assert "Invalid timestamp format" in result["message"]
-
-    # Verify retain_batch_async was NOT called
-    mock_memory.retain_batch_async.assert_not_called()
@@ -93,7 +93,7 @@ def test_per_operation_provider_default_model():
        config = HindsightConfig.from_env()

        # Global LLM should use OpenAI default
-        assert config.llm_model == "o3-mini", f"Expected o3-mini, got {config.llm_model}"
+        assert config.llm_model == "gpt-4o-mini", f"Expected gpt-4o-mini, got {config.llm_model}"

        # Retain should use Anthropic default
        assert (
@@ -0,0 +1,71 @@
+"""
+Regression test for UnboundLocalError in recall when the reranker raises.
+
+Before the fix, `scored_results` and `pre_filtered_count` were only assigned
+inside the `try` block, but referenced in the `finally` block.  If
+`reranker_instance.rerank()` (or `ensure_initialized()`) raised, the `finally`
+block crashed with `UnboundLocalError` instead of propagating the original
+exception.
+
+Fix: initialise both variables to safe defaults before the try/finally block.
+"""
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_recall_reranker_error_does_not_raise_unbound_local(memory, request_context):
+    """Recall must propagate the reranker's exception, not an UnboundLocalError."""
+    bank_id = f"test_reranker_err_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Paris is the capital of France",
+            request_context=request_context,
+        )
+
+        # Simulate a reranker failure (e.g. Cohere API error on empty/small candidate set)
+        rerank_mock = AsyncMock(side_effect=RuntimeError("reranker API error"))
+        memory._cross_encoder_reranker._initialized = True  # skip ensure_initialized
+
+        with patch.object(memory._cross_encoder_reranker, "rerank", rerank_mock):
+            with pytest.raises(Exception, match="reranker API error"):
+                await memory.recall_async(
+                    bank_id=bank_id,
+                    query="capital of France",
+                    request_context=request_context,
+                )
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_recall_reranker_init_error_does_not_raise_unbound_local(memory, request_context):
+    """Same regression when ensure_initialized() raises (before pre_filtered_count is set)."""
+    bank_id = f"test_reranker_init_err_{datetime.now(timezone.utc).timestamp()}"
+
+    try:
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Paris is the capital of France",
+            request_context=request_context,
+        )
+
+        init_mock = AsyncMock(side_effect=RuntimeError("reranker init failed"))
+        memory._cross_encoder_reranker._initialized = False
+
+        with patch.object(memory._cross_encoder_reranker, "ensure_initialized", init_mock):
+            with pytest.raises(Exception, match="reranker init failed"):
+                await memory.recall_async(
+                    bank_id=bank_id,
+                    query="capital of France",
+                    request_context=request_context,
+                )
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
@@ -1,6 +1,6 @@
 [package]
 name = "hindsight-cli"
-version = "0.4.11"
+version = "0.4.13"
 edition = "2021"
 authors = ["Hindsight Team"]
 description = "A beautiful CLI for Hindsight - semantic memory system"
@@ -266,6 +266,7 @@ pub fn recall(
                max_tokens: chunk_max_tokens,
            }),
            entities: None,
+            source_facts: None,
        })
    } else {
        None
@@ -22,7 +22,7 @@ go get golang.org/x/net/context
 Put the package under your project folder and add the following in import:

 ```go
-import hindsight "github.com/vectorize-io/hindsight-client-go"
+import hindsight "github.com/vectorize-io/hindsight/hindsight-clients/go"
 ```

 To use a proxy, set the environment variable `HTTP_PROXY`:
@@ -7,7 +7,7 @@ info:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Hindsight HTTP API
-  version: 0.4.11
+  version: 0.4.13
 servers:
 - url: /
 paths:
@@ -3226,6 +3226,8 @@ components:
          $ref: '#/components/schemas/EntityIncludeOptions'
        chunks:
          $ref: '#/components/schemas/ChunkIncludeOptions'
+        source_facts:
+          $ref: '#/components/schemas/SourceFactsIncludeOptions'
      title: IncludeOptions
    ListDocumentsResponse:
      description: Response model for list documents endpoint.
@@ -3724,6 +3726,10 @@ components:
          additionalProperties:
            $ref: '#/components/schemas/ChunkData'
          nullable: true
+        source_facts:
+          additionalProperties:
+            $ref: '#/components/schemas/RecallResult'
+          nullable: true
      required:
      - results
      title: RecallResponse
@@ -3789,6 +3795,11 @@ components:
            type: string
          nullable: true
          type: array
+        source_fact_ids:
+          items:
+            type: string
+          nullable: true
+          type: array
      required:
      - id
      - text
@@ -4083,9 +4094,6 @@ components:
      description: Request model for retain endpoint.
      example:
        async: false
-        document_tags:
-        - user_a
-        - user_b
        items:
        - content: Alice works at Google
          context: work
@@ -4148,6 +4156,15 @@ components:
      - items_count
      - success
      title: RetainResponse
+    SourceFactsIncludeOptions:
+      description: Options for including source facts for observation-type results.
+      properties:
+        max_tokens:
+          default: 4096
+          description: Maximum tokens for source facts
+          title: Max Tokens
+          type: integer
+      title: SourceFactsIncludeOptions
    TagItem:
      description: Single tag with usage count.
      properties:
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -41,7 +41,7 @@ var (
 	queryDescape    = strings.NewReplacer( "%5B", "[", "%5D", "]" )
 )

-// APIClient manages communication with the Hindsight HTTP API API v0.4.11
+// APIClient manages communication with the Hindsight HTTP API API v0.4.13
 // In most cases there should be only one, shared, APIClient.
 type APIClient struct {
 	cfg    *Configuration
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -1,4 +1,4 @@
-module github.com/vectorize-io/hindsight-client-go
+module github.com/vectorize-io/hindsight/hindsight-clients/go

 go 1.18

@@ -0,0 +1,41 @@
+package hindsight
+
+import (
+	"net/http"
+	"time"
+)
+
+// NewAPIClientWithToken creates a new API client configured with a base URL and API token.
+// The token is sent as a Bearer token in the Authorization header for all requests.
+// Note: this uses http.DefaultClient which has no timeout. Use NewAPIClientWithTimeout
+// to set a request timeout.
+//
+// Example:
+//
+//	client := hindsight.NewAPIClientWithToken("https://api.example.com", "your-api-token")
+//	resp, _, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
+func NewAPIClientWithToken(baseURL, token string) *APIClient {
+	cfg := NewConfiguration()
+	cfg.Servers = ServerConfigurations{
+		{URL: baseURL},
+	}
+	cfg.AddDefaultHeader("Authorization", "Bearer "+token)
+	return NewAPIClient(cfg)
+}
+
+// NewAPIClientWithTimeout creates a new API client configured with a base URL, API token,
+// and a request timeout. Use 0 for no timeout.
+//
+// Example:
+//
+//	client := hindsight.NewAPIClientWithTimeout("https://api.example.com", "your-api-token", 30*time.Second)
+//	resp, _, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
+func NewAPIClientWithTimeout(baseURL, token string, timeout time.Duration) *APIClient {
+	cfg := NewConfiguration()
+	cfg.Servers = ServerConfigurations{
+		{URL: baseURL},
+	}
+	cfg.AddDefaultHeader("Authorization", "Bearer "+token)
+	cfg.HTTPClient = &http.Client{Timeout: timeout}
+	return NewAPIClient(cfg)
+}
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -21,6 +21,7 @@ var _ MappedNullable = &IncludeOptions{}
 type IncludeOptions struct {
 	Entities NullableEntityIncludeOptions `json:"entities,omitempty"`
 	Chunks NullableChunkIncludeOptions `json:"chunks,omitempty"`
+	SourceFacts NullableSourceFactsIncludeOptions `json:"source_facts,omitempty"`
 }

 // NewIncludeOptions instantiates a new IncludeOptions object
@@ -124,6 +125,48 @@ func (o *IncludeOptions) UnsetChunks() {
 	o.Chunks.Unset()
 }

+// GetSourceFacts returns the SourceFacts field value if set, zero value otherwise (both if not set or set to explicit null).
+func (o *IncludeOptions) GetSourceFacts() SourceFactsIncludeOptions {
+	if o == nil || IsNil(o.SourceFacts.Get()) {
+		var ret SourceFactsIncludeOptions
+		return ret
+	}
+	return *o.SourceFacts.Get()
+}
+
+// GetSourceFactsOk returns a tuple with the SourceFacts field value if set, nil otherwise
+// and a boolean to check if the value has been set.
+// NOTE: If the value is an explicit nil, `nil, true` will be returned
+func (o *IncludeOptions) GetSourceFactsOk() (*SourceFactsIncludeOptions, bool) {
+	if o == nil {
+		return nil, false
+	}
+	return o.SourceFacts.Get(), o.SourceFacts.IsSet()
+}
+
+// HasSourceFacts returns a boolean if a field has been set.
+func (o *IncludeOptions) HasSourceFacts() bool {
+	if o != nil && o.SourceFacts.IsSet() {
+		return true
+	}
+
+	return false
+}
+
+// SetSourceFacts gets a reference to the given NullableSourceFactsIncludeOptions and assigns it to the SourceFacts field.
+func (o *IncludeOptions) SetSourceFacts(v SourceFactsIncludeOptions) {
+	o.SourceFacts.Set(&v)
+}
+// SetSourceFactsNil sets the value for SourceFacts to be an explicit nil
+func (o *IncludeOptions) SetSourceFactsNil() {
+	o.SourceFacts.Set(nil)
+}
+
+// UnsetSourceFacts ensures that no value is present for SourceFacts, not even an explicit nil
+func (o *IncludeOptions) UnsetSourceFacts() {
+	o.SourceFacts.Unset()
+}
+
 func (o IncludeOptions) MarshalJSON() ([]byte, error) {
 	toSerialize,err := o.ToMap()
 	if err != nil {
@@ -140,6 +183,9 @@ func (o IncludeOptions) ToMap() (map[string]interface{}, error) {
 	if o.Chunks.IsSet() {
 		toSerialize["chunks"] = o.Chunks.Get()
 	}
+	if o.SourceFacts.IsSet() {
+		toSerialize["source_facts"] = o.SourceFacts.Get()
+	}
 	return toSerialize, nil
 }

@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -25,6 +25,7 @@ type RecallResponse struct {
 	Trace map[string]interface{} `json:"trace,omitempty"`
 	Entities map[string]EntityStateResponse `json:"entities,omitempty"`
 	Chunks map[string]ChunkData `json:"chunks,omitempty"`
+	SourceFacts map[string]RecallResult `json:"source_facts,omitempty"`
 }

 type _RecallResponse RecallResponse
@@ -170,6 +171,39 @@ func (o *RecallResponse) SetChunks(v map[string]ChunkData) {
 	o.Chunks = v
 }

+// GetSourceFacts returns the SourceFacts field value if set, zero value otherwise (both if not set or set to explicit null).
+func (o *RecallResponse) GetSourceFacts() map[string]RecallResult {
+	if o == nil {
+		var ret map[string]RecallResult
+		return ret
+	}
+	return o.SourceFacts
+}
+
+// GetSourceFactsOk returns a tuple with the SourceFacts field value if set, nil otherwise
+// and a boolean to check if the value has been set.
+// NOTE: If the value is an explicit nil, `nil, true` will be returned
+func (o *RecallResponse) GetSourceFactsOk() (map[string]RecallResult, bool) {
+	if o == nil || IsNil(o.SourceFacts) {
+		return map[string]RecallResult{}, false
+	}
+	return o.SourceFacts, true
+}
+
+// HasSourceFacts returns a boolean if a field has been set.
+func (o *RecallResponse) HasSourceFacts() bool {
+	if o != nil && !IsNil(o.SourceFacts) {
+		return true
+	}
+
+	return false
+}
+
+// SetSourceFacts gets a reference to the given map[string]RecallResult and assigns it to the SourceFacts field.
+func (o *RecallResponse) SetSourceFacts(v map[string]RecallResult) {
+	o.SourceFacts = v
+}
+
 func (o RecallResponse) MarshalJSON() ([]byte, error) {
 	toSerialize,err := o.ToMap()
 	if err != nil {
@@ -190,6 +224,9 @@ func (o RecallResponse) ToMap() (map[string]interface{}, error) {
 	if o.Chunks != nil {
 		toSerialize["chunks"] = o.Chunks
 	}
+	if o.SourceFacts != nil {
+		toSerialize["source_facts"] = o.SourceFacts
+	}
 	return toSerialize, nil
 }

@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -33,6 +33,7 @@ type RecallResult struct {
 	Metadata map[string]string `json:"metadata,omitempty"`
 	ChunkId NullableString `json:"chunk_id,omitempty"`
 	Tags []string `json:"tags,omitempty"`
+	SourceFactIds []string `json:"source_fact_ids,omitempty"`
 }

 type _RecallResult RecallResult
@@ -497,6 +498,39 @@ func (o *RecallResult) SetTags(v []string) {
 	o.Tags = v
 }

+// GetSourceFactIds returns the SourceFactIds field value if set, zero value otherwise (both if not set or set to explicit null).
+func (o *RecallResult) GetSourceFactIds() []string {
+	if o == nil {
+		var ret []string
+		return ret
+	}
+	return o.SourceFactIds
+}
+
+// GetSourceFactIdsOk returns a tuple with the SourceFactIds field value if set, nil otherwise
+// and a boolean to check if the value has been set.
+// NOTE: If the value is an explicit nil, `nil, true` will be returned
+func (o *RecallResult) GetSourceFactIdsOk() ([]string, bool) {
+	if o == nil || IsNil(o.SourceFactIds) {
+		return nil, false
+	}
+	return o.SourceFactIds, true
+}
+
+// HasSourceFactIds returns a boolean if a field has been set.
+func (o *RecallResult) HasSourceFactIds() bool {
+	if o != nil && !IsNil(o.SourceFactIds) {
+		return true
+	}
+
+	return false
+}
+
+// SetSourceFactIds gets a reference to the given []string and assigns it to the SourceFactIds field.
+func (o *RecallResult) SetSourceFactIds(v []string) {
+	o.SourceFactIds = v
+}
+
 func (o RecallResult) MarshalJSON() ([]byte, error) {
 	toSerialize,err := o.ToMap()
 	if err != nil {
@@ -539,6 +573,9 @@ func (o RecallResult) ToMap() (map[string]interface{}, error) {
 	if o.Tags != nil {
 		toSerialize["tags"] = o.Tags
 	}
+	if o.SourceFactIds != nil {
+		toSerialize["source_fact_ids"] = o.SourceFactIds
+	}
 	return toSerialize, nil
 }

@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
@@ -3,7 +3,7 @@ Hindsight HTTP API

 HTTP API for Hindsight

-API version: 0.4.11
+API version: 0.4.13
 */

 // Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Nicolò Boschi	efbecb6423	fix: create report.pdf in working directory for retain.sh file upload examples	2026-02-20 15:40:35 +01:00
Nicolò Boschi	4b5b580410	fix: add include_facts to reflect client, fix retain.sh temp files, fix main-methods based_on access	2026-02-20 15:18:11 +01:00
Nicolò Boschi	f8eb0c84c2	doc: improve api explanation	2026-02-20 15:12:22 +01:00
Nicolò Boschi	23165c244c	doc: improve api explanation	2026-02-20 14:37:11 +01:00
Nicolò Boschi	7074893f70	doc: improve api explanation	2026-02-20 14:36:53 +01:00
Anton EvseevandClaude Opus 4.6	3f9eb27cd7	feat(openclaw): add autoRecall toggle and excludeProviders schema (#413 ) Add `autoRecall` config option (default: true) to allow disabling automatic memory recall injection when the host agent has its own dedicated recall tool. This is backward compatible — existing deployments continue auto-recalling as before. Also add the existing `excludeProviders` field to the plugin.json configSchema so it appears in the UI and docs. Co-authored-by: Claude Opus 4.6 <[email protected]>	2026-02-20 09:31:46 +01:00
Nicolò Boschi	13c82bab60	fix: set hindsight-crewai version to 0.4.13 (#412 )	2026-02-20 09:31:22 +01:00
Nicolò Boschi	4f431b4ace	doc: 0.4.13 changelog (#411 )	2026-02-19 20:48:50 +01:00
Nicolò Boschi	2993fdd2f9	Release v0.4.13 - Update version to 0.4.13 in all components - Regenerate OpenAPI spec and client SDKs - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed - Python client: hindsight-clients/python - TypeScript client: hindsight-clients/typescript - Rust CLI: hindsight-cli - Control Plane: hindsight-control-plane - OpenClaw integration: hindsight-integrations/openclaw - AI SDK integration: hindsight-integrations/ai-sdk - Helm chart - Sync documentation to version-0.4	2026-02-19 18:46:07 +01:00
Nicolò Boschi	325b5cc141	feat: switch default model to gpt-4o-mini (#410 )	2026-02-19 18:43:52 +01:00
Nicolò Boschi	0758827d39	fix: npx hindsight-control-plane fails (#408 )	2026-02-19 18:23:13 +01:00
Nicolò Boschi	ea8163c56d	fix(mcp): unify hindsight-mcp-local and server mcp (#407 ) * fix(mcp): stateless param not supported anymore * fixes * fix: npx hindsight-control-plane fails	2026-02-19 17:57:17 +01:00
Nicolò Boschi	ac73948706	fix: docker startup fails with named docker volumes (#405 )	2026-02-19 16:42:27 +01:00
Nicolò Boschi	5569d4adba	feat: include source facts in observation recall (#404 ) * feat: include source facts in observation recall * feat: include source facts in observation recall * feat: include source facts in observation recall * feat: include source facts in observation recall * fix(cli): add missing source_facts field to IncludeOptions initializer	2026-02-19 14:54:19 +01:00
Nicolò Boschi	e785b05831	fix(mcp): stateless param not supported anymore (#406 )	2026-02-19 13:42:54 +01:00
Nicolò Boschi	58c4d65778	fix: reranker crashes on provider error (#403 ) * fix: reranker crashes on provider error * fix: reranker crashes on provider error	2026-02-19 11:38:37 +01:00
Derek Bouius	c3ef1555bf	fix: reduce temporal ordering offset from 10s to 10ms per fact (#402 ) The 10-second offset per fact caused significant timestamp drift when ingesting many items — e.g. 600 facts would shift the last fact by ~100 minutes from its actual event time. This broke timeline views and made occurred_start/mentioned_at unreliable for temporal queries. Reducing to 10ms preserves fact ordering while keeping timestamps within ~8 seconds of the original values even for large batches.	2026-02-19 10:48:18 +01:00
Nicolò Boschi	dcaa9f14ab	fix: clients don't respect timeout setting (#400 )	2026-02-19 10:47:47 +01:00
BenandClaude Opus 4.6	41db2960c5	feat: add CrewAI integration for persistent crew memory (#319 ) * feat: add CrewAI integration for persistent crew memory Implements a CrewAI ExternalMemory storage backend that maps CrewAI's Storage interface (save/search/reset) to Hindsight's retain/recall/delete APIs, giving crews long-term memory with fact extraction, entity tracking, and temporal awareness across runs. Key features: - HindsightStorage: drop-in Storage backend for CrewAI ExternalMemory - HindsightReflectTool: BaseTool exposing Hindsight's reflect API - Per-agent memory banks with customizable bank resolver - Async compatibility layer for CrewAI's threading model - 35 unit tests, docs site page, example script Co-Authored-By: Claude Opus 4.6 <[email protected]> * refactor: move CrewAI example to hindsight-cookbook Move research_crew.py example from hindsight-integrations/crewai/examples/ to the cookbook repo and update the integration README to link there instead. Co-Authored-By: Claude Opus 4.6 <[email protected]> * ci: add GitHub Actions test job for CrewAI integration Co-Authored-By: Claude Opus 4.6 <[email protected]> * ci: add uv.lock for frozen installs in CI The test-crewai-integration CI job uses `uv sync --frozen` which requires a committed lock file. Co-Authored-By: Claude Opus 4.6 <[email protected]> --------- Co-authored-by: Claude Opus 4.6 <[email protected]>	2026-02-18 17:05:52 +01:00
Nicolò Boschi	f78278ea89	fix: document not tracked if has 0 extracted facts (#399 ) * fix: document not tracked if has 0 extracted facts * fix: document not tracked if has 0 extracted facts	2026-02-18 17:01:57 +01:00
Nicolò Boschi	117dd6988d	doc: changelog for 0.4.12 (#397 ) * changelog for 0.4.12 * changelog for 0.4.12	2026-02-18 14:55:19 +01:00
Nicolò Boschi	7c78ae2371	Release v0.4.12 - Update version to 0.4.12 in all components - Regenerate OpenAPI spec and client SDKs - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed - Python client: hindsight-clients/python - TypeScript client: hindsight-clients/typescript - Rust CLI: hindsight-cli - Control Plane: hindsight-control-plane - OpenClaw integration: hindsight-integrations/openclaw - AI SDK integration: hindsight-integrations/ai-sdk - Helm chart - Sync documentation to version-0.4	2026-02-18 14:13:33 +01:00
Nicolò Boschi	6c695eb9f8	fix: improve openclaw test coverage (#396 ) * fix: improve openclaw test coverage * test(openclaw): export stripMemoryTags/extractRecallQuery and add hook integration tests - Extract stripMemoryTags and extractRecallQuery as exported pure functions from index.ts so hooks share one implementation and tests cover the real code - Update before_agent_start to call extractRecallQuery; update agent_end to call stripMemoryTags instead of duplicating the regex inline - Rewrite index.test.ts to import the real functions (no more local duplicate) and add 11 tests for extractRecallQuery covering all envelope-stripping cases - Add tests/hooks.integration.test.ts: loads the plugin via mock MoltbotPluginAPI in HTTP mode, spies on client.recall/retain, and exercises all hook behaviours: excluded providers, short messages, memory injection format, tag stripping, transcript formatting, array content blocks, metadata, document_id derivation	2026-02-18 14:10:33 +01:00
Nicolò Boschi	7eafba661e	feat: add iris as file parser (#395 ) * feat: add iris as file parser * fix	2026-02-18 14:09:56 +01:00
Anton EvseevandClaude Opus 4.6	c461013047	fix(openclaw): shell safety, HTTP dual-mode, lazy reinit, per-user banks (#388 ) - exec→execFile: bypass shell entirely, preventing injection via special characters in chat history - HTTP dual-mode: client can now talk directly to the Hindsight API via HTTP (setBankMission, retain, recall) when apiUrl is configured, bypassing the subprocess/CLI entirely for production deployments - HindsightClientOptions: replace 5 positional constructor args with a typed options object for clarity and extensibility - sanitize(): strip null bytes from strings — Node 22 rejects them in execFile() args - recall timeout: accept optional timeoutMs parameter for both HTTP and subprocess modes; subprocess gets a longer 30s default - In-flight recall dedup: concurrent recalls for the same bank reuse one promise instead of firing duplicate requests - Timeout/abort handling: graceful warn-level logging instead of error spam when recall times out - Error cause chaining: wrap errors with { cause } for better debugging stack traces - lazyReinit: recover from startup health check failure with 30s cooldown and concurrency guard - Per-user banks: derive bank ID from senderId (not channelId) for proper memory isolation per user across channels - buildClientOptions(): centralized helper replaces 7 duplicated constructor call sites Co-authored-by: Claude Opus 4.6 <[email protected]>	2026-02-18 13:09:02 +01:00
Nicolò Boschi	7c99feb018	fix(go-client): add go build to CI (#393 ) * feat(go-client): add NewAPIClientWithToken helper and expand recall vs reflect FAQ - Add NewAPIClientWithToken convenience function to Go client for easy authenticated client creation - Expand FAQ with detailed "When should I use recall vs reflect?" guidance including practical examples * fix(go-client): add go build to CI and preserve hindsight_client.go in generator - Add explicit 'go build ./...' step before integration tests for faster compile feedback - Preserve hindsight_client.go as a maintained file in generate-clients.sh	2026-02-18 13:06:17 +01:00
Nicolò Boschi	d06a0259cc	feat: improve ai sdk tools (#394 )	2026-02-18 13:06:03 +01:00
Eliah RusinandClaude Opus 4.6	be8728b313	fix(go-client): use monorepo-compatible module path (#392 ) The Go SDK declared its module as github.com/vectorize-io/hindsight-client-go, but that repository doesn't exist. Update to github.com/vectorize-io/hindsight/hindsight-clients/go to match the actual monorepo path, enabling standard `go get` imports with directory-prefixed tags. Also enables isGoSubmodule in the OpenAPI generator config and updates all import references across tests, docs, and the client generation script. Co-authored-by: Claude Opus 4.6 <[email protected]>	2026-02-18 10:35:13 +01:00
Derek Bouius	917893aac7	fix: restore entity retrieval in recall (#391 ) Entity retrieval was removed in `ab5e31f2` ("chore: remove dead code") but the code was not dead — it populated the entities dict and per-fact entity names returned by the recall endpoint. This restores: - fact_entity_map query joining unit_entities and entities tables - entity_names on each MemoryFact result - entities_dict with EntityState objects ordered by fact relevance - entity count in recall log line	2026-02-18 10:33:58 +01:00