doc: fix build

Author: nicoloboschi

hindsight-docs/docs/developer/installation.md

@@ -246,5 +246,5 @@ See the [Python SDK](../sdks/python.md) for the full API reference.
 ## Next Steps
 
 - [Configuration](./configuration.md) — Environment variables and settings
-- [Models](./models.md) — ML models and providers
+- [Models](./models.mdx) — ML models and providers
 - [Monitoring](./monitoring.md) — Metrics and observability

hindsight-docs/versioned_docs/version-0.4/developer/api/quickstart.mdx

@@ -9,12 +9,17 @@ Get up and running with Hindsight in 60 seconds.
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeSnippet from '@site/src/components/CodeSnippet';
+import {ClientsGrid, IntegrationsGrid} from '@site/src/components/SupportedGrids';
 
 {/* Import raw source files */}
 import quickstartPy from '!!raw-loader!@site/examples/api/quickstart.py';
 import quickstartMjs from '!!raw-loader!@site/examples/api/quickstart.mjs';
 import quickstartSh from '!!raw-loader!@site/examples/api/quickstart.sh';
 
+## Clients
+
+<ClientsGrid />
+
 ## Start the API Server
 
 <Tabs>
@@ -100,6 +105,10 @@ curl -fsSL https://hindsight.vectorize.io/get-cli | bash
 
 ---
 
+## Integrations
+
+<IntegrationsGrid />
+
 ## Next Steps
 
 - [**Retain**](./retain) — Advanced options for storing memories

hindsight-docs/versioned_docs/version-0.4/developer/api/recall.mdx

@@ -184,6 +184,66 @@ Use this for strict scope enforcement where a memory must explicitly belong to *
 A memory with tags `["user:alice", "team", "project:x"]` will still match a filter of `["user:alice", "team"]` under `all_strict` — extra tags on the memory are not a problem. The filter only requires the memory to contain **at least** the specified tags.
 :::
 
+### tag_groups
+
+`tag_groups` is a list of compound boolean tag filters. The groups in the list are AND-ed together at the top level. Each group is a recursive boolean expression: a **leaf** node `{tags, match}`, or a **compound** node `{and: [...]}`, `{or: [...]}`, or `{not: ...}`.
+
+`tag_groups` and `tags` / `tags_match` can be used simultaneously — they are AND-ed together.
+
+#### Leaf node
+
+```json
+{ "tags": ["step:5", "step:8"], "match": "any_strict" }
+```
+
+`match` accepts the same values as `tags_match`: `any`, `all`, `any_strict`, `all_strict`. Defaults to `any_strict`.
+
+#### Compound nodes
+
+```json
+{ "and": [ <TagGroup>, <TagGroup>, ... ] }
+{ "or":  [ <TagGroup>, <TagGroup>, ... ] }
+{ "not": <TagGroup> }
+```
+
+#### Examples
+
+**Step filter AND user scope** — two top-level groups AND-ed:
+
+```json
+{
+  "tag_groups": [
+    { "tags": ["step:5", "step:8", "step:12"], "match": "any_strict" },
+    { "tags": ["user:ep_42"], "match": "all_strict" }
+  ]
+}
+```
+
+**Nested OR inside AND** — user must match, plus either step OR priority:
+
+```json
+{
+  "tag_groups": [
+    { "tags": ["user:alice"], "match": "all_strict" },
+    { "or": [
+        { "tags": ["step:5"], "match": "any_strict" },
+        { "tags": ["priority:high"], "match": "all_strict" }
+    ]}
+  ]
+}
+```
+
+**Exclusion** — user must match, but archived memories are excluded:
+
+```json
+{
+  "tag_groups": [
+    { "tags": ["user:alice"], "match": "all_strict" },
+    { "not": { "tags": ["archived"], "match": "any_strict" } }
+  ]
+}
+```
+
 ### trace
 
 When set to `true`, the response includes a detailed debug trace covering the query embedding, entry points, per-strategy retrieval results, RRF fusion candidates, reranked results, temporal constraints detected, and per-phase timings. Has no effect on the retrieval logic itself. Useful for understanding why specific memories were or were not returned.

hindsight-docs/versioned_docs/version-0.4/developer/configuration.md

@@ -160,7 +160,7 @@ To switch between backends:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_LLM_PROVIDER` | Provider: `openai`, `openai-codex`, `claude-code`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio`, `vertexai` | `openai` |
+| `HINDSIGHT_API_LLM_PROVIDER` | Provider: `openai`, `openai-codex`, `claude-code`, `anthropic`, `gemini`, `groq`, `minimax`, `ollama`, `lmstudio`, `vertexai` | `openai` |
 | `HINDSIGHT_API_LLM_API_KEY` | API key for LLM provider | - |
 | `HINDSIGHT_API_LLM_MODEL` | Model name | `gpt-5-mini` |
 | `HINDSIGHT_API_LLM_BASE_URL` | Custom LLM endpoint | Provider default |
@@ -410,7 +410,7 @@ Supported OpenAI embedding dimensions:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `zeroentropy`, `flashrank`, `litellm`, `litellm-sdk`, or `rrf` | `local` |
+| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `zeroentropy`, `flashrank`, `litellm`, `litellm-sdk`, `jina-mlx`, or `rrf` | `local` |
 | `HINDSIGHT_API_RERANKER_LOCAL_MODEL` | Model for local provider | `cross-encoder/ms-marco-MiniLM-L-6-v2` |
 | `HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT` | Max concurrent local reranking (prevents CPU thrashing under load) | `4` |
 | `HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` |
@@ -426,10 +426,12 @@ Supported OpenAI embedding dimensions:
 | `HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY` | LiteLLM **SDK** API key for direct reranking (no proxy needed) | - |
 | `HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL` | LiteLLM SDK rerank model (e.g., `deepinfra/Qwen3-reranker-8B`) | `cohere/rerank-english-v3.0` |
 | `HINDSIGHT_API_RERANKER_LITELLM_SDK_API_BASE` | Custom API base URL for LiteLLM SDK (optional) | - |
+| `HINDSIGHT_API_RERANKER_LITELLM_MAX_TOKENS_PER_DOC` | Truncate documents to this many tokens before sending to the reranker (applies to both `litellm` and `litellm-sdk`). Use for models with small context windows (e.g. set to `900` for a 1024-token limit model). Unset by default (no truncation). | - |
 | `HINDSIGHT_API_RERANKER_ZEROENTROPY_API_KEY` | ZeroEntropy API key for reranking | - |
 | `HINDSIGHT_API_RERANKER_ZEROENTROPY_MODEL` | ZeroEntropy rerank model (`zerank-2`, `zerank-2-small`) | `zerank-2` |
 | `HINDSIGHT_API_RERANKER_FLASHRANK_MODEL` | FlashRank model for fast CPU-based reranking | `ms-marco-MiniLM-L-12-v2` |
 | `HINDSIGHT_API_RERANKER_FLASHRANK_CACHE_DIR` | Cache directory for FlashRank models | System default |
+| `HINDSIGHT_API_RERANKER_JINA_MLX_MODEL_PATH` | Local path to downloaded `jina-reranker-v3-mlx` model (auto-downloads from HuggingFace if unset) | - |
 
 ```bash
 # Local (default) - uses SentenceTransformers CrossEncoder
@@ -472,6 +474,10 @@ export HINDSIGHT_API_RERANKER_LITELLM_MODEL=cohere/rerank-english-v3.0  # or voy
 export HINDSIGHT_API_RERANKER_PROVIDER=litellm-sdk
 export HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY=your-deepinfra-api-key
 export HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL=deepinfra/Qwen3-reranker-8B  # or cohere/rerank-english-v3.0, etc.
+
+# Jina MLX - Apple Silicon native reranking (no GPU/cloud required)
+# Model (~1.2 GB) is downloaded automatically from HuggingFace Hub on first use.
+export HINDSIGHT_API_RERANKER_PROVIDER=jina-mlx
 ```
 
 #### LiteLLM Proxy vs SDK
@@ -488,6 +494,14 @@ Both support the same providers:
 - **Jina AI** (`jina_ai/jina-reranker-v2`)
 - **AWS Bedrock** (`bedrock/...`)
 
+#### Jina MLX (Apple Silicon)
+
+The `jina-mlx` provider uses [`jinaai/jina-reranker-v3-mlx`](https://huggingface.co/jinaai/jina-reranker-v3-mlx), optimized for Apple Silicon. The model (~1.2 GB) is downloaded from HuggingFace Hub automatically on first startup and cached locally.
+
+:::note License
+`jina-reranker-v3-mlx` is licensed under CC BY-NC 4.0. Contact Jina AI for commercial usage.
+:::
+
 ### Authentication
 
 By default, Hindsight runs without authentication. For production deployments, enable API key authentication using the built-in tenant extension:
@@ -530,6 +544,7 @@ For advanced authentication (JWT, OAuth, multi-tenant schemas), implement a cust
 | `HINDSIGHT_API_GRAPH_RETRIEVER` | Graph retrieval algorithm: `link_expansion`, `mpfp`, or `bfs` | `link_expansion` |
 | `HINDSIGHT_API_RECALL_MAX_CONCURRENT` | Max concurrent recall operations per worker (backpressure) | `32` |
 | `HINDSIGHT_API_RECALL_CONNECTION_BUDGET` | Max concurrent DB connections per recall operation | `4` |
+| `HINDSIGHT_API_RECALL_MAX_QUERY_TOKENS` | Maximum token length of a recall query; requests exceeding this limit are rejected with HTTP 400 | `500` |
 | `HINDSIGHT_API_RERANKER_MAX_CANDIDATES` | Max candidates to rerank per recall (RRF pre-filters the rest) | `300` |
 | `HINDSIGHT_API_MPFP_TOP_K_NEIGHBORS` | Fan-out limit per node in MPFP graph traversal | `20` |
 | `HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY` | Max concurrent mental model refreshes | `8` |

…oned_docs/version-0.4/developer/index.md …ned_docs/version-0.4/developer/index.mdxhindsight-docs/versioned_docs/version-0.4/developer/index.md renamed to hindsight-docs/versioned_docs/version-0.4/developer/index.mdx hindsight-docs/versioned_docs/version-0.4/developer/index.md renamed to hindsight-docs/versioned_docs/version-0.4/developer/index.mdx

@@ -3,6 +3,8 @@ sidebar_position: 1
 slug: /
 ---
 
+import {ClientsGrid, IntegrationsGrid} from '@site/src/components/SupportedGrids';
+
 # Overview
 
 ## Why Hindsight?
@@ -114,6 +116,14 @@ The **mission** tells Hindsight what knowledge to prioritize and provides contex
 
 These settings only affect the `reflect` operation, not `recall`.
 
+## Clients & Languages
+
+<ClientsGrid />
+
+## Integrations
+
+<IntegrationsGrid />
+
 ## Next Steps
 
 ### Getting Started

hindsight-docs/versioned_docs/version-0.4/developer/installation.md

@@ -8,28 +8,28 @@ Hindsight can be deployed in several ways depending on your infrastructure and r
 
 ## Prerequisites
 
-### PostgreSQL with pgvector
+### PostgreSQL
 
-Hindsight requires PostgreSQL with the **pgvector** extension for vector similarity search.
+Hindsight requires PostgreSQL 14+ with a vector extension for similarity search. The supported extensions are:
+
+- **pgvector** (default)
+- **pgvectorscale**
+- **vchord**
+
+Configure which one to use with `HINDSIGHT_API_VECTOR_EXTENSION`. See [Configuration](./configuration) for details.
 
 **By default**, Hindsight uses **pg0** — an embedded PostgreSQL that runs locally on your machine. This is convenient for development but **not recommended for production**.
 
-**For production**, use an external PostgreSQL with pgvector:
+**For production**, use an external PostgreSQL with one of the supported vector extensions:
 - **Supabase** — Managed PostgreSQL with pgvector built-in
 - **Neon** — Serverless PostgreSQL with pgvector
-- **Azure Database for PostgreSQL** — With pgvector and pg_diskann (DiskANN) support
+- **Azure Database for PostgreSQL** — With pgvector and pgvectorscale support
 - **AWS RDS** / **Cloud SQL** — With pgvector extension enabled
-- **Self-hosted** — PostgreSQL 14+ with pgvector installed
+- **Self-hosted** — PostgreSQL 14+ with your preferred vector extension
 
 ### LLM Provider
 
-You need an LLM API key for fact extraction, entity resolution, and answer generation:
-
-- **Groq** (recommended): Fast inference with `gpt-oss-20b`
-- **OpenAI**: GPT-4o, GPT-4o-mini
-- **Ollama**: Run models locally
-
-See [Models](./models) for detailed comparison and configuration.
+You need an LLM API key for fact extraction, entity resolution, and answer generation. See [Models](./models) for supported providers, model recommendations, and configuration.
 
 ---
 
@@ -53,61 +53,12 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
 
 ### Docker Image Variants
 
-Hindsight provides two image variants with different size/capability tradeoffs:
+| Variant | Size (AMD64) | Size (ARM64) | When to use |
+|---------|--------------|--------------|-------------|
+| **Full** (`latest`) | ~9 GB | ~3.7 GB | Default. Works out of the box with no external services except the LLM. |
+| **Slim** (`slim`) | ~500 MB | ~500 MB | Use when you already rely on external services for embeddings and reranking (OpenAI, Cohere, TEI). Significantly smaller image, faster deploys. Requires [external providers](./configuration#embeddings). |
 
-| Variant | Size (AMD64) | Size (ARM64) | Use Case |
-|---------|--------------|--------------|----------|
-| **Full** (`latest`) | ~9 GB | ~3.7 GB | Includes local ML models (embeddings, reranking) |
-| **Slim** (`slim`) | ~500 MB | ~500 MB | Requires external embedding/reranking providers |
-
-**Full image** (default):
-```bash
-docker run --rm -it -p 8888:8888 \
-  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-  ghcr.io/vectorize-io/hindsight:latest
-```
-- ✅ Works out of the box with local ML models
-- ✅ No additional services needed
-- ❌ Larger image size (AMD64 includes CUDA libraries for GPU support)
-
-**Slim image**:
-```bash
-docker run --rm -it -p 8888:8888 \
-  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-  -e HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai \
-  -e HINDSIGHT_API_RERANKER_PROVIDER=cohere \
-  -e HINDSIGHT_API_COHERE_API_KEY=$COHERE_API_KEY \
-  ghcr.io/vectorize-io/hindsight:latest-slim
-```
-- ✅ Dramatically smaller image (~95% reduction on AMD64)
-- ✅ Faster pull/deploy times
-- ✅ Lower memory footprint
-- ❌ Requires external embedding/reranking services (OpenAI, Cohere, TEI)
-
-**When to use slim:**
-- Cloud deployments where image size matters
-- Using managed embedding services (OpenAI, Cohere)
-- Running on Text Embeddings Inference (TEI) infrastructure
-- Kubernetes environments with fast pull requirements
-
-:::warning Slim Image Requires External Providers
-If you run the slim image **without** setting external embedding providers, you'll see this error:
-
-```
-ImportError: sentence-transformers is required for LocalSTEmbeddings.
-Install it with: pip install sentence-transformers
-```
-
-**Fix:** Always set embedding and reranking providers when using slim images:
-```bash
--e HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
--e HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=sk-xxx
--e HINDSIGHT_API_RERANKER_PROVIDER=cohere
--e HINDSIGHT_API_COHERE_API_KEY=xxx
-```
-:::
-
-See [Configuration](./configuration#embeddings) for all embedding provider options.
+The slim image corresponds to the [`hindsight-api-slim`](#bare-metal-pip) pip package. See [Configuration](./configuration#embeddings) for external provider options.
 
 ### Available Tags
 
@@ -120,7 +71,7 @@ ghcr.io/vectorize-io/hindsight:0.4.9-slim    # Slim, specific version
 
 # API only
 ghcr.io/vectorize-io/hindsight-api:latest
-ghcr.io/vectorize-io/hindsight-api:slim
+ghcr.io/vectorize-io/hindsight-api:latest-slim
 
 # Control Plane only
 ghcr.io/vectorize-io/hindsight-control-plane:latest
@@ -175,14 +126,17 @@ See the [Helm chart values.yaml](https://github.com/vectorize-io/hindsight/tree/
 
 ## Bare Metal (pip)
 
-**Best for**: Custom deployments, integration into existing Python applications
+**Best for**: Running Hindsight as a standalone service on a host machine.
 
 ### Install
 
 ```bash
-pip install hindsight-all
+pip install hindsight-api        # Full — works out of the box
+pip install hindsight-api-slim   # Slim — requires external services for embeddings, reranking, and the database
 ```
 
+When using `hindsight-api-slim`, you must configure external providers for all model operations. See [Configuration](./configuration#embeddings) for details.
+
 ### Run with Embedded Database
 
 For development and testing, Hindsight can run with an embedded PostgreSQL (pg0):
@@ -253,8 +207,44 @@ PORT=80 HINDSIGHT_CP_DATAPLANE_API_URL=https://api.hindsight.io npx @vectorize-i
 
 ---
 
+## Embedded in a Python Application
+
+**Best for**: Using Hindsight programmatically from Python without running a separate server process.
+
+```bash
+pip install hindsight-all        # Full — works out of the box
+pip install hindsight-all-slim   # Slim — requires external services for embeddings, reranking, and the database
+```
+
+`hindsight-all` supports two modes of embedding:
+
+**In-process** (`HindsightServer`): the server runs in a background thread inside your application. Best when you want the tightest integration and are already managing your own process lifecycle.
+
+```python
+from hindsight import HindsightServer, HindsightClient
+
+with HindsightServer(llm_provider="openai", llm_api_key="sk-xxx") as server:
+    client = HindsightClient(base_url=server.url)
+    client.retain(bank_id="alice", content="Alice prefers concise answers.")
+    results = client.recall(bank_id="alice", query="How should I respond to Alice?")
+```
+
+**Managed subprocess** (`HindsightEmbedded`): the server runs as a background daemon process, shared across multiple Python processes or sessions. The daemon starts on first use and shuts down automatically after an idle timeout.
+
+```python
+from hindsight import HindsightEmbedded
+
+client = HindsightEmbedded(llm_provider="openai", llm_api_key="sk-xxx")
+client.retain(bank_id="alice", content="Alice prefers concise answers.")
+results = client.recall(bank_id="alice", query="How should I respond to Alice?")
+```
+
+See the [Python SDK](../sdks/python.md) for the full API reference.
+
+---
+
 ## Next Steps
 
 - [Configuration](./configuration.md) — Environment variables and settings
-- [Models](./models.md) — ML models and providers
+- [Models](./models.mdx) — ML models and providers
 - [Monitoring](./monitoring.md) — Metrics and observability