From 61a8014f9d5e9b50ce76e92e670debc8ce4d8f4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Wed, 8 Apr 2026 18:45:20 +0200 Subject: [PATCH] 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 --- .../blog/2026-04-07-version-0-5-0.md | 221 ++++++++++++++++++ hindsight-docs/docs/developer/models.mdx | 1 + hindsight-docs/src/pages/changelog/index.md | 52 +++++ 3 files changed, 274 insertions(+) create mode 100644 hindsight-docs/blog/2026-04-07-version-0-5-0.md diff --git a/hindsight-docs/blog/2026-04-07-version-0-5-0.md b/hindsight-docs/blog/2026-04-07-version-0-5-0.md new file mode 100644 index 00000000..966b5821 --- /dev/null +++ b/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. + + + +- [**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). diff --git a/hindsight-docs/docs/developer/models.mdx b/hindsight-docs/docs/developer/models.mdx index a3ad02ec..ab056ad5 100644 --- a/hindsight-docs/docs/developer/models.mdx +++ b/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: diff --git a/hindsight-docs/src/pages/changelog/index.md b/hindsight-docs/src/pages/changelog/index.md index 9d5fb2ca..01310c65 100644 --- a/hindsight-docs/src/pages/changelog/index.md +++ b/hindsight-docs/src/pages/changelog/index.md @@ -6,6 +6,58 @@ import PageHero from '@site/src/components/PageHero'; +## [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**