docs: update 0.4.15 blog cover image

hindsight-docs/blog/2026-03-03-version-0-4-15.md

@@ -0,0 +1,216 @@
+---
+title: "What's new in Hindsight 0.4.15"
+description: New features and improvements in Hindsight 0.4.15
+authors: [hindsight]
+date: 2026-03-03
+hide_table_of_contents: true
+image: /img/blog/release0415.png
+---
+
+Hindsight 0.4.15 adds PydanticAI integration, observation scopes, richer entity labels, and several performance improvements—alongside a set of reliability and stability fixes.
+
+<!-- truncate -->
+
+- [**PydanticAI Integration**](#pydanticai-integration): Add persistent memory to PydanticAI agents.
+- [**Observation Scopes**](#observation-scopes): Control how facts consolidate into observations across tag dimensions.
+- [**Richer Entity Labels**](#richer-entity-labels): Optional labels, free-form values, and multi-value fields for entity extraction.
+- [**Timestamp Unset**](#timestamp-unset): Retain timeless content without a date.
+- [**Performance**](#performance): Recall and retain are faster and more scalable for large memory banks.
+
+## PydanticAI Integration
+
+Hindsight now integrates with [PydanticAI](https://ai.pydantic.dev/), letting you attach persistent memory to any PydanticAI agent with a few lines of code.
+
+```python
+from hindsight_client import Hindsight
+from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions
+from pydantic_ai import Agent
+
+client = Hindsight(base_url="http://localhost:8888")
+
+agent = Agent(
+    "openai:gpt-4o",
+    tools=create_hindsight_tools(client=client, bank_id="user-123"),
+    instructions=[memory_instructions(client=client, bank_id="user-123")],
+)
+
+result = await agent.run("What do you remember about my preferences?")
+print(result.output)
+```
+
+`create_hindsight_tools` registers three async tools on the agent:
+
+- **`hindsight_retain`** — stores information to long-term memory
+- **`hindsight_recall`** — searches memory for relevant facts
+- **`hindsight_reflect`** — synthesizes a reasoned answer from stored memories
+
+`memory_instructions` injects recalled context as instructions at the start of every run, so the agent always has relevant history in its context window without needing to call a tool explicitly.
+
+Both accept the full set of Hindsight retrieval parameters—`budget`, `max_tokens`, `tags`, `recall_tags`, and `recall_tags_match`—for fine-grained control over what gets stored and retrieved.
+
+You can also configure defaults globally:
+
+```python
+from hindsight_pydantic_ai import configure, create_hindsight_tools
+
+configure(
+    hindsight_api_url="http://localhost:8888",
+    api_key="your-api-key",       # Or set HINDSIGHT_API_KEY env var
+    budget="mid",                  # Recall budget: low/mid/high
+    max_tokens=4096,               # Max tokens for recall results
+    tags=["env:prod"],             # Tags for stored memories
+    recall_tags=["scope:global"],  # Tags to filter recall
+    recall_tags_match="any",       # Tag match mode: any/all/any_strict/all_strict
+)
+
+# Now create tools without passing client — uses global config
+tools = create_hindsight_tools(bank_id="user-123")
+```
+
+See the [PydanticAI integration documentation](/sdks/integrations/pydantic-ai) for a full quickstart.
+
+## Observation Scopes
+
+Observations are Hindsight's higher-level summaries derived from raw facts. Previously, observations were always consolidated across all tags at once. Now you can control the _granularity_ of each consolidation pass with `observation_scopes`.
+
+This matters when memories are tagged across multiple dimensions—say, `student:alice`, `teacher:bob`, and `session-id:s1`. You might want observations per-student, per-teacher, and per-session independently, not just one combined observation for all three.
+
+`observation_scopes` is a per-item parameter passed in the retain request. The examples below use a lesson transcript retained with `tags: ["student:alice", "teacher:bob", "session-id:s1"]`.
+
+**`per_tag`** — one consolidation pass per individual tag. The most common choice for multi-party content.
+
+- Observations created: `["student:alice"]` · `["teacher:bob"]` · `["session-id:s1"]`
+- Queries like _"What does Alice struggle with?"_ and _"How does Bob teach?"_ match.
+- Queries like _"How does Alice perform specifically with Bob?"_ do not — no observation was built for that combination.
+
+**`combined`** *(default)* — one pass using all tags together.
+
+- Observations created: `["student:alice", "teacher:bob", "session-id:s1"]`
+- Only the exact combination matches. Individual tags like `["student:alice"]` do not.
+
+**`all_combinations`** — one pass per subset. For 3 tags that is 7 passes.
+
+- Observations created: all `per_tag` scopes plus every pair and the full set.
+
+**`custom`** — explicit list of tag sets:
+
+```json
+[["student:alice"], ["teacher:bob"], ["teacher:bob", "session-id:s1"]]
+```
+
+Only those three scopes are built — nothing more.
+
+Scopes are fully isolated during consolidation—a memory consolidated under `["student:alice"]` will never bleed into an observation tagged `["student:alice", "teacher:bob"]`.
+
+## Richer Entity Labels
+
+`entity_labels` is a new bank configuration option that defines a controlled vocabulary of `key:value` classification labels. During retain, the LLM extracts these labels from each piece of content and stores them as entities. Because labels become entities, they automatically link memories in the knowledge graph and improve both semantic and BM25 retrieval.
+
+Three field types are supported:
+
+| Type | Behavior |
+|------|----------|
+| `"value"` | Single value from a fixed list |
+| `"multi-values"` | One or more values from a fixed list |
+| `"text"` | Free-form string (no fixed values) |
+
+Fields can also be marked `optional: true` so the LLM skips them when the content doesn't have enough information.
+
+```json
+{
+  "entity_labels": [
+    {
+      "key": "engagement",
+      "description": "Student engagement level during the session",
+      "type": "value",
+      "optional": true,
+      "values": [
+        { "value": "active",  "description": "Student is actively participating" },
+        { "value": "passive", "description": "Student is listening but not participating" }
+      ]
+    },
+    {
+      "key": "pedagogy",
+      "description": "Teaching strategies used",
+      "type": "multi-values",
+      "values": [
+        { "value": "scaffolding",          "description": "Breaking complex tasks into smaller steps" },
+        { "value": "direct_instruction",   "description": "Explicit explanation by the teacher" },
+        { "value": "socratic_questioning", "description": "Guiding through questions rather than answers" }
+      ]
+    },
+    {
+      "key": "topic",
+      "description": "Specific subject being discussed. Examples: algebra, quadratic equations, geometry.",
+      "type": "text",
+      "optional": true
+    }
+  ]
+}
+```
+
+For enum types (`"value"`, `"multi-values"`), anything outside the `values` list is silently dropped—vocabulary stays stable and graph links stay tight. For `"text"` types, the LLM writes any string; use `description` to provide examples and guidance.
+
+Set `entity_labels` via the [bank config API](/developer/api/memory-banks#entity-labels). The control plane UI has been updated to display multi-value and free-form labels cleanly.
+
+## Timestamp Unset
+
+When retaining reference material—documentation, books, or any content without a meaningful event date—you can now pass `timestamp="unset"` to tell Hindsight there is no real date to associate with the content.
+
+```python
+# Timeless reference content
+client.retain(
+    bank_id="my-bank",
+    content="The quick sort algorithm has O(n log n) average-case time complexity.",
+    timestamp="unset"
+)
+
+# Mix timeless and timestamped content in a single batch
+client.retain_batch(
+    bank_id="my-bank",
+    items=[
+        {"content": "Meeting notes...", "timestamp": "2026-03-01T14:00:00Z"},
+        {"content": "Company handbook...", "timestamp": "unset"},
+    ]
+)
+```
+
+When `"unset"` is passed, the fact-extraction prompt shows `Event Date: Unknown`, allowing the model to correctly return `N/A` for the `when` field of every extracted fact rather than anchoring facts to an arbitrary date.
+
+## Performance
+
+This release includes significant database-level work targeting large-scale memory banks—better indices, improved query planning, reduced lock contention, deadlock fixes, and connection warmup improvements. We benchmarked against banks with up to 100,000 memories and 100 million entity links:
+
+- **Retain**: Up to **10x faster** at large scale.
+- **Recall**: Up to **~20x better** at very large scale, with the largest gains in the graph and temporal retrievers.
+
+No configuration is required.
+
+## Other Updates
+
+**Features**
+- **OpenClaw auto-retain**: OpenClaw now retains the last `N*2 + 4` messages every N turns (default N=10) instead of every turn. The sliding window ensures conversation context is never lost at boundaries while significantly reducing LLM calls per session. Configure with `retainEveryNTurns` in the plugin config.
+- **Gemini/Vertex AI safety settings**: Safety settings for Gemini and Vertex AI LLM calls are now configurable. Useful for deployments that need to relax or tighten content filtering on LLM calls.
+- **Document tag filtering**: The list documents API now supports filtering by tags, making it easier to query which documents were retained under a given label.
+- **Extension hooks**: New hooks to customize root routing behavior and add custom error headers, for deployments that need to intercept requests or decorate responses at the transport layer.
+
+**Bug Fixes**
+- Fixed reflect failing with `context_length_exceeded` on large memory banks by truncating the context window correctly.
+- Fixed a consolidation deadlock caused by retrying after zombie processing tasks.
+- Fixed the observations count in the control plane that always showed 0.
+- Fixed JSON serialization issues and logging-related exception propagation with the `claude_code` LLM provider.
+- Fixed the ZeroEntropy rerank endpoint URL.
+- Fixed MCP `async_processing` parameter handling.
+- Added bank-scoped request validation to prevent cross-bank operations.
+- Fixed the TypeScript SDK to send `null` (not `undefined`) when `includeEntities` is `false`.
+
+## Feedback and Community
+
+Hindsight 0.4.15 is a drop-in replacement for 0.4.x with no breaking changes.
+
+Share your feedback:
+
+- [GitHub Discussions](https://github.com/vectorize-io/hindsight/discussions)
+- [GitHub Issues](https://github.com/vectorize-io/hindsight/issues)
+
+For detailed changes, see the [full changelog](/changelog).

hindsight-docs/src/pages/changelog.md

@@ -8,6 +8,34 @@ This changelog highlights user-facing changes only. Internal maintenance, CI/CD,
 
 For full release details, see [GitHub Releases](https://github.com/vectorize-io/hindsight/releases).
 
+## [0.4.15](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.15)
+
+**Features**
+
+- Added observation_scopes to control the granularity/visibility of observations. ([`55af4681`](https://github.com/vectorize-io/hindsight/commit/55af4681))
+- List documents API now supports filtering by tags (and fixes the q parameter description). ([`1d70abfe`](https://github.com/vectorize-io/hindsight/commit/1d70abfe))
+- Added PydanticAI integration for persistent agent memory. ([`cab5a40f`](https://github.com/vectorize-io/hindsight/commit/cab5a40f))
+- Added richer entity label support (optional labels, free-form values, multi-value fields, and UI polish). ([`9b96becc`](https://github.com/vectorize-io/hindsight/commit/9b96becc))
+- Added support for timestamp="unset" so content can be retained without a date. ([`f903948a`](https://github.com/vectorize-io/hindsight/commit/f903948a))
+- OpenClaw can now automatically retain the last n+2 turns every n turns (default n=10). ([`ad1660b3`](https://github.com/vectorize-io/hindsight/commit/ad1660b3))
+- Added configurable Gemini/Vertex AI safety settings for LLM calls. ([`73ef99e7`](https://github.com/vectorize-io/hindsight/commit/73ef99e7))
+- Added extension hooks to customize root routing and error headers. ([`e407f4bc`](https://github.com/vectorize-io/hindsight/commit/e407f4bc))
+
+**Improvements**
+
+- Improved recall performance by fetching all recall chunks in a single query. ([`61bf428b`](https://github.com/vectorize-io/hindsight/commit/61bf428b))
+- Improved recall/retain performance and scalability for large memory banks. ([`7942f181`](https://github.com/vectorize-io/hindsight/commit/7942f181))
+
+**Bug Fixes**
+
+- Fixed the TypeScript SDK to send null (not undefined) when includeEntities is false. ([`15f4b876`](https://github.com/vectorize-io/hindsight/commit/15f4b876))
+- Prevented reflect from failing with context_length_exceeded on large memory banks. ([`77defd96`](https://github.com/vectorize-io/hindsight/commit/77defd96))
+- Fixed a consolidation deadlock caused by retrying after zombie processing tasks. ([`c2876490`](https://github.com/vectorize-io/hindsight/commit/c2876490))
+- Fixed observations count in the control plane that always showed 0. ([`eaeaa1f2`](https://github.com/vectorize-io/hindsight/commit/eaeaa1f2))
+- Fixed ZeroEntropy rerank endpoint URL and ensured the MCP retain async_processing parameter is handled correctly. ([`f6f1a7d8`](https://github.com/vectorize-io/hindsight/commit/f6f1a7d8))
+- Fixed JSON serialization issues and logging-related exception propagation when using the claude_code LLM provider. ([`ecb833f4`](https://github.com/vectorize-io/hindsight/commit/ecb833f4))
+- Added bank-scoped request validation to prevent cross-bank/invalid bank operations. ([`5270aa5a`](https://github.com/vectorize-io/hindsight/commit/5270aa5a))
+
 ## [0.4.14](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.14)
 
 **Features**
@@ -18,7 +46,7 @@ For full release details, see [GitHub Releases](https://github.com/vectorize-io/
 - Support filtering graph-based memory retrieval by tags. ([`0bb5ca4c`](https://github.com/vectorize-io/hindsight/commit/0bb5ca4c))
 - Add batch observations consolidation to process multiple observations more efficiently. ([`0aa7c2b3`](https://github.com/vectorize-io/hindsight/commit/0aa7c2b3))
 - Add OpenClaw options to toggle autoRecall and exclude specific providers. ([`3f9eb27c`](https://github.com/vectorize-io/hindsight/commit/3f9eb27c))
-- - Add a ZeroEntropy reranker provider option. ([`17259675`](https://github.com/vectorize-io/hindsight/commit/17259675))
+- Add a ZeroEntropy reranker provider option. ([`17259675`](https://github.com/vectorize-io/hindsight/commit/17259675))
 
 **Improvements**