docs: 0.5.0 release notes, changelog, and blog post (#907)

* docs: add 0.5.0 release notes and changelog

* docs: include all commits since v0.4.22 and add recall perf to blog

* docs: include all commits since v0.4.22 and add recall perf to blog

* docs: add openrouter default model to provider table

* docs: reorder blog sections, fix code snippets, remove paperclip

* docs: add hermes integration docs link

* docs: fix broken anchor in blog post TOC

hindsight-docs/blog/2026-04-07-version-0-5-0.md

@@ -0,0 +1,221 @@
+---
+title: "What's new in Hindsight 0.5.0"
+description: New features and improvements in Hindsight 0.5.0
+authors: [nicoloboschi]
+date: 2026-04-07T12:00
+hide_table_of_contents: true
+---
+
+Hindsight 0.5.0 introduces the Bank Template Hub for portable configuration, a Constellation graph view in the Control Plane, major retain and recall performance improvements, new LLM providers (llama.cpp, OpenRouter, Google), retain append mode, new framework integrations (AutoGen, OpenCode), and a breaking removal of legacy graph retrieval strategies and the Hermes integration.
+
+<!-- truncate -->
+
+- [**Bank Template Hub**](#bank-template-hub): Export and import full bank configurations as reusable manifests.
+- [**Constellation View**](#constellation-view): Interactive entity graph visualization in the Control Plane.
+- [**Performance: Retain and Recall**](#performance-retain-and-recall): 3-phase retain pipeline and capped entity graph expansion for faster queries.
+- [**New LLM Providers**](#new-llm-providers): Built-in llama.cpp for local inference, OpenRouter, and Google embeddings/reranker.
+- [**Retain Append Mode**](#retain-append-mode): Concatenate new content onto existing documents with `update_mode='append'`.
+- [**AutoGen Integration**](#autogen-integration): Persistent memory for AutoGen agents.
+- [**Breaking Changes**](#breaking-changes): BFS/MPFP strategies removed; Hermes integration dropped.
+
+## Bank Template Hub
+
+Banks can now be exported as portable template manifests that capture the full configuration — settings, mental models, and directives — in a single JSON document. Import a manifest into any bank to replicate the setup instantly.
+
+The manifest format captures everything needed to reproduce a bank's behavior:
+
+```json
+{
+  "version": "1",
+  "bank": {
+    "retain_mission": "Extract customer issues, resolutions, and sentiment.",
+    "enable_observations": true,
+    "observations_mission": "Track recurring customer pain points."
+  },
+  "mental_models": [
+    {
+      "id": "sentiment-overview",
+      "name": "Customer Sentiment Overview",
+      "source_query": "What is the overall sentiment trend?",
+      "trigger": { "refresh_after_consolidation": true }
+    }
+  ],
+  "directives": [
+    {
+      "name": "Acknowledge frustration",
+      "content": "Always acknowledge frustration before offering solutions.",
+      "priority": 10
+    }
+  ]
+}
+```
+
+A dry-run mode (`dry_run=True`) validates manifests without applying changes, and a schema endpoint returns the full JSON Schema for tooling integration. Mental models are matched by `id` and directives by `name` — existing entries are updated, new ones are created.
+
+This is particularly useful for teams standardizing agent configurations or sharing proven bank setups across projects.
+
+See the [Bank Template Hub documentation](/developer/api/bank-templates) for the full manifest schema and API reference.
+
+## Constellation View
+
+The Control Plane now includes an interactive Constellation view that renders memory entity graphs as a zoomable, pannable canvas. Nodes represent entities and their positions are deterministically computed, so the layout is stable across visits.
+
+Links are color-coded by type — semantic (blue), temporal (teal), entity (amber), causal (purple) — and node color intensity maps to connectivity: brighter nodes have more connections. The view supports dark mode automatically and is built on the `@chenglou/pretext` layout engine for smooth text rendering at any zoom level.
+
+Click any node to navigate to its entity detail page, or zoom out for a birds-eye view of how memories connect across your bank.
+
+## Performance: Retain and Recall
+
+### 3-Phase Retain Pipeline
+
+The retain pipeline has been restructured into three distinct phases to eliminate database lock contention under concurrent load:
+
+1. **Pre-resolve** — Entity resolution and semantic ANN search run outside a transaction on read-only connections, preventing slow reads from blocking writes.
+2. **Insert** — Facts, temporal links, semantic links, and causal links are written atomically in a single transaction, ensuring retrieval consistency.
+3. **Post-link** — Entity co-occurrence links (used only for UI visualization) are built after the transaction commits, as a best-effort background step.
+
+Previously, the entire pipeline ran inside one long transaction, meaning concurrent agents would queue behind each other during the O(bank_size) ANN lookup. The new structure moves all read-heavy work out of the critical write path, resulting in dramatically lower latency when many agents write simultaneously.
+
+### Capped Entity Graph Expansion
+
+On large banks, the entity co-occurrence self-join in graph expansion could produce massive intermediate row counts when seed results reference high-fanout entities (e.g. an entity mentioned 25K+ times). This caused recall latency to spike unpredictably.
+
+The graph expansion query now uses a LATERAL per-entity cap (`graph_per_entity_limit`, default 200), reducing intermediate rows from potentially millions to at most `num_entities × 200`. Results are recency-biased via `ORDER BY unit_id DESC`, which rides the primary key index with no extra sort cost. A timeout fallback (`graph_expansion_timeout`, default 10s) drops entity expansion entirely and falls back to semantic + causal signals if the query still takes too long.
+
+A new composite index on `(entity_id, unit_id)` in `unit_entities` enables index-only scans for the capped subquery, keeping the expansion fast even on very large banks.
+
+## New LLM Providers
+
+### Built-in llama.cpp
+
+Hindsight now ships with a built-in llama.cpp LLM provider, enabling fully local inference without any external API calls. Set the provider to `llama-cpp` and point it at a GGUF model file:
+
+```bash
+HINDSIGHT_API_LLM_PROVIDER=llama-cpp
+HINDSIGHT_API_LLM_MODEL=/path/to/model.gguf
+```
+
+This is ideal for air-gapped environments, development setups, or anywhere you want to avoid external API costs. The provider uses the `llama-cpp-python` bindings and supports all standard Hindsight LLM operations (fact extraction, consolidation, reflect).
+
+### OpenRouter
+
+Hindsight now supports [OpenRouter](https://openrouter.ai/) as a provider for LLM, embeddings, and reranking. This gives you access to hundreds of models through a single API key:
+
+```bash
+HINDSIGHT_API_LLM_PROVIDER=openrouter
+HINDSIGHT_API_LLM_API_KEY=sk-or-...
+HINDSIGHT_API_LLM_MODEL=anthropic/claude-sonnet-4-20250514
+```
+
+OpenRouter is particularly useful for comparing models or accessing providers that don't have a direct Hindsight integration yet.
+
+### Google Embeddings and Reranker
+
+Google is now supported as a provider for embeddings and reranking, complementing the existing Gemini LLM provider support.
+
+## Retain Append Mode
+
+A new `update_mode='append'` option for retain lets you concatenate new content onto an existing document instead of replacing it. This is useful for streaming or incremental ingestion scenarios — for example, appending new log entries or conversation turns to an existing document:
+
+```python
+from hindsight_client import Hindsight
+
+client = Hindsight(base_url="http://localhost:8888")
+
+# First retain creates the document
+client.retain(bank_id="my-bank", content="Day 1 notes...", document_id="journal")
+
+# Subsequent retains append instead of replacing
+client.retain(bank_id="my-bank", content="Day 2 notes...", document_id="journal", update_mode="append")
+```
+
+The default `update_mode` remains `replace` for backward compatibility.
+
+## AutoGen Integration
+
+`hindsight-autogen` provides persistent long-term memory for [AutoGen](https://github.com/microsoft/autogen) agents via three `FunctionTool` wrappers: `hindsight_retain`, `hindsight_recall`, and `hindsight_reflect`.
+
+```bash
+pip install hindsight-autogen
+```
+
+```python
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from hindsight_client import Hindsight
+from hindsight_autogen import create_hindsight_tools
+
+client = Hindsight(base_url="http://localhost:8888")
+await client.acreate_bank(bank_id="user-123")
+
+model_client = OpenAIChatCompletionClient(model="gpt-4o")
+tools = create_hindsight_tools(client=client, bank_id="user-123")
+
+agent = AssistantAgent(
+    name="assistant",
+    model_client=model_client,
+    tools=tools,
+)
+
+await agent.run(task="Remember that I prefer dark mode")
+await agent.run(task="What are my UI preferences?")
+```
+
+The integration supports memory scoping via tags, fact type filtering, custom metadata, and selective tool inclusion. Use `configure()` to set global defaults like budget, max tokens, and tag filters.
+
+See the [AutoGen integration documentation](/sdks/integrations/autogen) for the full API reference.
+
+## Breaking Changes
+
+### Graph Retrieval Simplification
+
+The BFS (breadth-first spreading activation) and MPFP (multi-path fact propagation) graph retrieval strategies have been removed. `LinkExpansionRetriever` is now the sole graph retrieval algorithm.
+
+LinkExpansionRetriever operates on three precomputed, first-class signals — entity links, semantic kNN links, and causal links — without iterative graph walks or fan-out caps. It is simpler to maintain, faster at query time, and empirically more accurate in our benchmarks.
+
+**Migration:** If you were explicitly selecting BFS or MPFP via configuration, remove that setting. The default has been LinkExpansionRetriever since 0.4.x, so most deployments require no changes.
+
+### Hermes Integration Dropped
+
+The `hindsight-hermes` integration package has been removed. Hermes Agent now ships with a native Hindsight memory provider built into the framework itself, making the external integration package unnecessary. See the [Hermes integration documentation](/sdks/integrations/hermes) for setup instructions with the native provider.
+
+## Other Updates
+
+**Features**
+- Added OpenCode persistent memory plugin for the OpenCode editor.
+- Helm chart now supports persistent volumes for local model cache.
+- MCP server adds a `sync_retain` tool and validates UUID inputs.
+- OpenClaw now supports `bankId` for static bank configurations.
+- Recall combined scoring includes `proof_count` boost for better ranking.
+- Fact serialization in think-prompt now includes `occurred_end` and `mentioned_at` for richer temporal context.
+
+**Improvements**
+- Consolidation observation quality improved with structured processing rules for better synthesis.
+- OpenClaw gains a JSONL-backed retain queue that buffers retain calls locally when the external API is unreachable, preventing data loss during outages.
+- LiteLLM SDK embeddings `encoding_format` is now configurable instead of hardcoded.
+
+**Bug Fixes**
+- Fixed out-of-range `content_index` crash in recall result mapping.
+- Experience fact types are now preserved correctly during normalization instead of being silently reclassified.
+- `clear memories` endpoint no longer deletes the bank profile along with the memories.
+- Embedding daemon clears stale processes on the port before starting, preventing startup failures.
+- Per-bank vector index migration now respects the configured vector extension.
+- Timeline group sort uses numeric date comparison instead of locale string comparison.
+- MCP server auto-coerces string-encoded JSON in tool arguments.
+- Entity labels structure validated on PATCH to prevent invalid configurations.
+- Fixed `bank_id` metric label to be opt-in, preventing OTel memory leak.
+- Fixed `max_tokens` handling for OpenAI-compatible endpoints with custom base URLs.
+- Query analyzer handles dateparser internal crashes gracefully.
+- Windows compatibility fix for hindsight-embed.
+- Addressed critical and high severity security vulnerabilities in dependencies.
+
+## Feedback and Community
+
+**Note:** Hindsight 0.5.0 contains breaking changes (BFS/MPFP removal, Hermes integration dropped). If you were using the default graph retrieval strategy, no action is needed. If you were using `hindsight-hermes`, switch to the native Hermes memory provider.
+
+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/docs/developer/models.mdx

@@ -94,6 +94,7 @@ Each provider has a recommended default model that's used when `HINDSIGHT_API_LL
 | `claude-code` | `claude-sonnet-4-5-20250929` |
 | `bedrock` | `us.amazon.nova-2-lite-v1:0` |
 | `volcano` | `doubao-pro-32k` |
+| `openrouter` | `qwen/qwen3.5-9b` |
 | `litellm` | `gpt-4o-mini` |
 
 **Example:** Setting just the provider uses its default model:

hindsight-docs/src/pages/changelog/index.md

@@ -6,6 +6,58 @@ import PageHero from '@site/src/components/PageHero';
 
 <PageHero title="Changelog" subtitle="User-facing changes only. Internal maintenance and infrastructure updates are omitted." />
 
+## [0.5.0](https://github.com/vectorize-io/hindsight/releases/tag/v0.5.0)
+
+**Breaking Changes**
+
+- Removed BFS and MPFP graph retrieval strategies. LinkExpansionRetriever is now the sole graph retrieval algorithm, offering simpler, faster, and more accurate results. ([`ea834bc7`](https://github.com/vectorize-io/hindsight/commit/ea834bc7))
+- Dropped the `hindsight-hermes` integration package. ([`cf0537ba`](https://github.com/vectorize-io/hindsight/commit/cf0537ba))
+
+**Features**
+
+- Built-in llama.cpp LLM provider for fully local inference without external API calls. ([`f74b577e`](https://github.com/vectorize-io/hindsight/commit/f74b577e))
+- Retain `update_mode='append'` for concatenating new content onto an existing document instead of replacing it. ([`3c633e5e`](https://github.com/vectorize-io/hindsight/commit/3c633e5e))
+- OpenRouter support for LLM, embeddings, and reranking. ([`e5944b63`](https://github.com/vectorize-io/hindsight/commit/e5944b63))
+- Bank template import/export with Template Hub — export a bank's configuration, mental models, and directives as a reusable manifest, then import into other banks. ([`30a319a6`](https://github.com/vectorize-io/hindsight/commit/30a319a6))
+- Constellation view in the Control Plane — interactive, zoomable canvas visualization of entity relationship graphs with heat-gradient coloring and dark mode support. ([`36783df3`](https://github.com/vectorize-io/hindsight/commit/36783df3))
+- Added `detail` parameter to list/get mental model endpoints for controlling response verbosity. ([`8d1bfbbd`](https://github.com/vectorize-io/hindsight/commit/8d1bfbbd))
+- Added AutoGen integration (`hindsight-autogen`) for persistent long-term memory in AutoGen agents. ([`a757765a`](https://github.com/vectorize-io/hindsight/commit/a757765a))
+- Added Paperclip integration (`@vectorize-io/hindsight-paperclip`) with Express middleware and process adapter modes for stateless agent memory. ([`81441ee9`](https://github.com/vectorize-io/hindsight/commit/81441ee9))
+- Added OpenCode persistent memory plugin for the OpenCode editor. ([`e1c6220f`](https://github.com/vectorize-io/hindsight/commit/e1c6220f))
+- OpenClaw JSONL-backed retain queue for external API resilience — buffers retain calls locally when the API is unreachable. ([`087545cc`](https://github.com/vectorize-io/hindsight/commit/087545cc))
+- OpenClaw now supports `bankId` for static bank configurations. ([`0e81d1a2`](https://github.com/vectorize-io/hindsight/commit/0e81d1a2))
+- Added Google embeddings and reranker provider support. ([`07de798c`](https://github.com/vectorize-io/hindsight/commit/07de798c))
+- Added persistent volume support in Helm chart for local model cache. ([`cefa7554`](https://github.com/vectorize-io/hindsight/commit/cefa7554))
+- MCP server now includes a `sync_retain` tool and validates UUID inputs. ([`48185a4b`](https://github.com/vectorize-io/hindsight/commit/48185a4b))
+- Recall combined scoring now includes `proof_count` boost for better ranking. ([`26794aab`](https://github.com/vectorize-io/hindsight/commit/26794aab))
+
+**Improvements**
+
+- 3-phase retain pipeline restructures memory ingestion into pre-resolve, insert, and post-link phases, dramatically improving throughput under concurrent load by removing slow reads from write transactions. ([`914ba796`](https://github.com/vectorize-io/hindsight/commit/914ba796))
+- Recall entity graph expansion now caps per-entity fanout and includes a timeout fallback, preventing slow queries on banks with high-fanout entities. ([`57f15445`](https://github.com/vectorize-io/hindsight/commit/57f15445))
+- Fact serialization in think-prompt now includes `occurred_end` and `mentioned_at` for richer temporal context. ([`37348c85`](https://github.com/vectorize-io/hindsight/commit/37348c85))
+- Consolidation observation quality improved with structured processing rules. ([`6f173b10`](https://github.com/vectorize-io/hindsight/commit/6f173b10))
+
+**Bug Fixes**
+
+- LiteLLM SDK embeddings `encoding_format` is now configurable instead of hardcoded. ([`cece2c90`](https://github.com/vectorize-io/hindsight/commit/cece2c90))
+- Fixed out-of-range `content_index` crash in recall result mapping. ([`9790d904`](https://github.com/vectorize-io/hindsight/commit/9790d904))
+- Experience fact types are now preserved correctly during normalization. ([`9cfdd464`](https://github.com/vectorize-io/hindsight/commit/9cfdd464))
+- Clear memories endpoint no longer deletes the bank profile. ([`26a64cc0`](https://github.com/vectorize-io/hindsight/commit/26a64cc0))
+- Embedding daemon clears stale processes on the port before starting. ([`7d6c570a`](https://github.com/vectorize-io/hindsight/commit/7d6c570a))
+- Per-bank vector index migration now respects vector extension configuration. ([`4fd7c5d1`](https://github.com/vectorize-io/hindsight/commit/4fd7c5d1))
+- Timeline group sort uses numeric date comparison instead of locale string comparison. ([`f3f2c6b0`](https://github.com/vectorize-io/hindsight/commit/f3f2c6b0))
+- Resolved 25 test regressions from the streaming retain pipeline. ([`7415ebff`](https://github.com/vectorize-io/hindsight/commit/7415ebff))
+- MCP server now auto-coerces string-encoded JSON in tool arguments. ([`443c94c8`](https://github.com/vectorize-io/hindsight/commit/443c94c8))
+- Entity labels structure is now validated on PATCH to prevent invalid configurations. ([`7e23f8e1`](https://github.com/vectorize-io/hindsight/commit/7e23f8e1))
+- Fixed `bank_id` metric label to be opt-in, preventing OTel memory leak. ([`cf4bd598`](https://github.com/vectorize-io/hindsight/commit/cf4bd598))
+- Fixed `max_tokens` handling for OpenAI-compatible endpoints with custom base URLs. ([`cd99eef4`](https://github.com/vectorize-io/hindsight/commit/cd99eef4))
+- Fixed `event_date` AttributeError when date is None in fact extraction. ([`6cb309f7`](https://github.com/vectorize-io/hindsight/commit/6cb309f7))
+- Query analyzer now handles dateparser internal crashes gracefully. ([`e0e65c44`](https://github.com/vectorize-io/hindsight/commit/e0e65c44))
+- Embedding profile `.env` overwrite skipped when config has no Hindsight keys. ([`9e2890ba`](https://github.com/vectorize-io/hindsight/commit/9e2890ba))
+- Windows compatibility fix for hindsight-embed. ([`f9fe6953`](https://github.com/vectorize-io/hindsight/commit/f9fe6953))
+- Addressed critical and high severity security vulnerabilities in dependencies. ([`ee4510a7`](https://github.com/vectorize-io/hindsight/commit/ee4510a7))
+
 ## [0.4.22](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.22)
 
 **Features**