diff --git a/hindsight-docs/blog/2026-03-24-version-0-4-20.md b/hindsight-docs/blog/2026-03-24-version-0-4-20.md new file mode 100644 index 00000000..606cc040 --- /dev/null +++ b/hindsight-docs/blog/2026-03-24-version-0-4-20.md @@ -0,0 +1,198 @@ +--- +title: "What's new in Hindsight 0.4.20" +description: New features and improvements in Hindsight 0.4.20 +authors: [nicoloboschi] +date: 2026-03-24 +hide_table_of_contents: true +image: /img/blog/release0420.png +--- + +Hindsight 0.4.20 adds Claude Code and LangGraph integrations, a NemoClaw setup CLI, independent versioning for integration packages, and reflect improvements including fact type filters, mental model exclusion, and a wall-clock timeout—plus a batch of reliability fixes. + + + +- [**Claude Code Integration**](#claude-code-integration): Give Claude Code persistent long-term memory via a hook-based plugin. +- [**LangGraph Integration**](#langgraph-integration): Use Hindsight memory in LangGraph agents with tools, nodes, or the BaseStore API. +- [**NemoClaw Integration**](#nemoclaw-integration): One-command Hindsight setup inside NemoClaw sandboxes. +- [**Independent Integration Versioning**](#independent-integration-versioning): Integrations now have their own version numbers and release lifecycle. +- [**Reflect Improvements**](#reflect-improvements): Fact type filters, mental model exclusion, and a wall-clock timeout. + +## Claude Code Integration + +`hindsight-memory` is a new plugin that gives [Claude Code](https://docs.anthropic.com/en/docs/claude-code) persistent long-term memory. It works in interactive sessions and through Claude Code Channels (Telegram, Discord, Slack). + +Install from the marketplace: + +```bash +# Add the Hindsight marketplace and install the plugin +claude plugin marketplace add vectorize-io/hindsight +claude plugin install hindsight-memory + +# Configure your LLM provider for memory extraction +# Option A: OpenAI (auto-detected) +export OPENAI_API_KEY="sk-your-key" + +# Option B: Anthropic (auto-detected) +export ANTHROPIC_API_KEY="your-key" + +# Option C: No API key needed (uses Claude Code's own model) +export HINDSIGHT_LLM_PROVIDER=claude-code + +# Start Claude Code — the plugin activates automatically +claude +``` + +The plugin uses four Claude Code hooks to manage memory automatically: + +- **SessionStart** — verifies Hindsight is reachable and optionally starts a local daemon. +- **UserPromptSubmit** — auto-recalls relevant memories and injects them as context. +- **Stop** — auto-retains the conversation transcript to long-term memory. +- **SessionEnd** — cleanup and optional daemon shutdown. + +Three connection modes are supported: + +1. **External API** — point `hindsightApiUrl` and `hindsightApiToken` at a remote Hindsight server. +2. **Local daemon** — leave `hindsightApiUrl` empty and the plugin auto-starts a local instance via `uvx hindsight-embed@latest`. Just provide an LLM API key. +3. **Existing local server** — set `apiPort` to match a server you already run. + +Dynamic bank IDs let you isolate memories per agent, project, session, channel, or user—controlled by the `dynamicBankId` and `dynamicBankGranularity` settings. The plugin ships as pure Python with zero external dependencies. + +See the [Claude Code integration documentation](/sdks/integrations/claude-code) for the full configuration reference, and the [Claude Code + Telegram + Hindsight](/blog/2026/03/23/claude-code-telegram) blog post for a walkthrough of using it with Claude Code Channels. + +## LangGraph Integration + +`hindsight-langgraph` adds Hindsight memory to [LangGraph](https://github.com/langchain-ai/langgraph) agents with three integration patterns. + +```bash +pip install hindsight-langgraph +``` + +**Tools** — works with both LangChain and LangGraph: + +```python +from hindsight_client import Hindsight +from hindsight_langgraph import create_hindsight_tools +from langchain_openai import ChatOpenAI + +client = Hindsight(base_url="http://localhost:8888") +tools = create_hindsight_tools(client=client, bank_id="user-123") + +model = ChatOpenAI(model="gpt-4o").bind_tools(tools) +``` + +**Memory nodes** — dedicated recall and retain nodes for LangGraph graphs: + +```python +from hindsight_client import Hindsight +from hindsight_langgraph import create_recall_node, create_retain_node + +client = Hindsight(base_url="http://localhost:8888") + +recall = create_recall_node(client=client, bank_id="user-123") +retain = create_retain_node(client=client, bank_id="user-123") + +builder.add_node("recall", recall) +builder.add_node("retain", retain) +``` + +**BaseStore** — LangGraph-native checkpoint memory backed by Hindsight: + +```python +from hindsight_client import Hindsight +from hindsight_langgraph import HindsightStore + +client = Hindsight(base_url="http://localhost:8888") +store = HindsightStore(client=client) + +graph = builder.compile(checkpointer=checkpointer, store=store) + +await store.aput(("user", "123", "prefs"), "theme", {"value": "dark mode"}) +results = await store.asearch(("user", "123", "prefs"), query="theme preference") +``` + +Multi-tenant routing is built in—pass `bank_id_from_config="user_id"` to any node or tool factory, and the bank ID is resolved dynamically from the LangGraph `configurable` dict at runtime. + +See the [LangGraph integration documentation](/sdks/integrations/langgraph) for the full API reference. + +## NemoClaw Integration + +`hindsight-nemoclaw` is a new integration that automates the five-step process of adding Hindsight memory to a [NemoClaw](https://nemoclaw.ai) sandbox: + +```bash +npx @vectorize-io/hindsight-nemoclaw setup \ + --sandbox my-assistant \ + --api-url https://api.hindsight.vectorize.io \ + --api-token \ + --bank-prefix my-sandbox +``` + +The CLI handles plugin installation, configuration, network policy updates (so the sandbox can reach the Hindsight API), and gateway restart. Use `--dry-run` to preview changes before applying. + +See the [NemoClaw integration documentation](/sdks/integrations/nemoclaw) for the full setup guide. + +## Independent Integration Versioning + +Integration packages—LiteLLM, Pydantic AI, CrewAI, AI SDK, Chat, OpenClaw, LangGraph, and NemoClaw—now have their own version numbers and release lifecycle, decoupled from the core Hindsight server. + +Previously, every integration was bumped and published together with each core release, even when nothing changed. This made it hard to tell whether a new version of an integration contained actual changes or was just a no-op bump. + +Starting with 0.4.20, each integration is versioned and released independently. What this means for you: + +- **Version numbers reflect real changes**: when you see a new version of `hindsight-langgraph` or `hindsight-litellm` on PyPI/npm, it contains actual updates to that package. +- **Faster integration fixes**: a bug fix or feature in one integration ships as soon as it's ready, without waiting for the next core release. +- **Per-integration changelogs**: each integration now has its own changelog page at `/changelog/integrations/` so you can track what changed in the packages you use. + +## Reflect Improvements + +Three additions make reflect more controllable and predictable. + +**Fact type filters** — `fact_types` restricts which fact types the reflection agent retrieves. Pass a subset of `["world", "experience", "observation"]` to limit the search scope and save LLM tokens: + +```json +{ + "query": "What does the user prefer?", + "fact_types": ["experience", "observation"] +} +``` + +**Mental model exclusion** — `exclude_mental_models` skips mental model search entirely, and `exclude_mental_model_ids` excludes specific models by ID. These filters also work in mental model triggers, so you can persist them on auto-refreshing models. The reflect agent enforces filters at the tool level—if the LLM tries to call a disabled tool, it receives an error rather than silently returning results from excluded sources. + +**Wall-clock timeout** — reflect operations now enforce a configurable timeout (default: 300 seconds). Previously, a slow LLM provider or high iteration count could cause a reflect call to hang for up to 40 minutes. When the timeout fires, the API returns HTTP 504. + +```bash +HINDSIGHT_API_REFLECT_WALL_TIMEOUT=300 # seconds +``` + +## Other Updates + +**Improvements** +- The `hindsight-api` package is now runnable directly via `uvx hindsight-api` thanks to new script entry points. +- The default MiniMax model has been upgraded from M2.5 to M2.7. +- The OperationValidator extension now receives richer context when validating operations. +- OpenAI-compatible client initialization now supports passing query parameters for broader provider compatibility. + +**Bug Fixes** +- Fixed a memory leak in entity resolution where `_pending_stats` and `_pending_cooccurrences` dicts could grow unbounded when exceptions occurred between fact extraction and flush. +- Fixed startup crash and silent retain failures when the PostgreSQL `pg_trgm` extension is unavailable. The migration now handles missing `pg_trgm` gracefully, and entity resolution falls back to full table scan with a warning. +- Fixed context overflow in reflect by disabling source facts in observation search results. +- Markdown code fences are now stripped from LLM outputs across all providers, not just local models. +- Empty recall queries now return a clear 400 error instead of failing with a SQL parameter gap. +- File retain requests now include authentication headers so uploads work in authenticated deployments. +- Fixed MCP tool calls failing when `MCP_AUTH_TOKEN` and `TENANT_API_KEY` differ. +- Fixed `claude-agent-sdk` installation on Linux/Docker environments. +- LiteLLM integration now falls back to the last user message when no explicit `hindsight_query` is provided. +- Fixed non-atomic async operation creation that could produce inconsistent operation records. +- Fixed orphaned parent operations when a batch retain child fails via unhandled exception. +- Fixed failures for non-ASCII entity names by ensuring entity IDs are set correctly. +- Fixed LLM facts labeled "assistant" being stored with the wrong fact type instead of "experience". + +## Feedback and Community + +Hindsight 0.4.20 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). diff --git a/hindsight-docs/src/pages/changelog/index.md b/hindsight-docs/src/pages/changelog/index.md index 82b28107..e514ce67 100644 --- a/hindsight-docs/src/pages/changelog/index.md +++ b/hindsight-docs/src/pages/changelog/index.md @@ -6,6 +6,42 @@ import PageHero from '@site/src/components/PageHero'; +## [0.4.20](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.20) + +**Features** + +- Add a one-command setup CLI package for the NemoClaw integration. ([`d284de28`](https://github.com/vectorize-io/hindsight/commit/d284de28)) +- Add a LangGraph integration for using Hindsight memory within LangGraph agents. ([`b4320254`](https://github.com/vectorize-io/hindsight/commit/b4320254)) +- Add reflect filters to exclude specific fact types and mental model content during reflection. ([`ea662d06`](https://github.com/vectorize-io/hindsight/commit/ea662d06)) +- Introduce independent versioning for integrations so they can be released separately from the core server. ([`31f1c53c`](https://github.com/vectorize-io/hindsight/commit/31f1c53c)) +- Add a Claude Code integration plugin. ([`f4390bdc`](https://github.com/vectorize-io/hindsight/commit/f4390bdc)) + +**Improvements** + +- Add a wall-clock timeout to reflect operations so they don’t run indefinitely. ([`8ce06e3e`](https://github.com/vectorize-io/hindsight/commit/8ce06e3e)) +- Provide richer context when validating operations via the OperationValidator extension. ([`2eb1019d`](https://github.com/vectorize-io/hindsight/commit/2eb1019d)) +- Make the hindsight-api package runnable directly via uvx by adding script entry points. ([`97f7a365`](https://github.com/vectorize-io/hindsight/commit/97f7a365)) +- Support passing query parameters during OpenAI-compatible client initialization for broader provider compatibility. ([`20e17f28`](https://github.com/vectorize-io/hindsight/commit/20e17f28)) +- Upgrade the default MiniMax model from M2.5 to M2.7. ([`1f1462a5`](https://github.com/vectorize-io/hindsight/commit/1f1462a5)) + +**Bug Fixes** + +- Prevent context overflow during observation search by disabling source facts in results. ([`8e2e2d5b`](https://github.com/vectorize-io/hindsight/commit/8e2e2d5b)) +- Fix Claude Code integration session startup by pre-starting the daemon in the background. ([`26944e25`](https://github.com/vectorize-io/hindsight/commit/26944e25)) +- Fix Claude Code integration installation and configuration experience so setup is more reliable. ([`35b2cbb6`](https://github.com/vectorize-io/hindsight/commit/35b2cbb6)) +- Fix a memory leak in entity resolution that could grow over time under load. ([`e6333719`](https://github.com/vectorize-io/hindsight/commit/e6333719)) +- Avoid crashes and retain failures when the Postgres pg_trgm extension is unavailable by handling detection/fallback correctly. ([`365fa3ce`](https://github.com/vectorize-io/hindsight/commit/365fa3ce)) +- Strip Markdown code fences from model outputs across all LLM providers for more consistent parsing. ([`2f2db2a6`](https://github.com/vectorize-io/hindsight/commit/2f2db2a6)) +- Return a clear 400 error for empty recall queries and fix a SQL parameterization issue. ([`5cdc714a`](https://github.com/vectorize-io/hindsight/commit/5cdc714a)) +- Ensure file retain requests include authentication headers so uploads work in authenticated deployments. ([`78aa7c53`](https://github.com/vectorize-io/hindsight/commit/78aa7c53)) +- Fix MCP tool calls when MCP_AUTH_TOKEN and TENANT_API_KEY differ. ([`8364b9c5`](https://github.com/vectorize-io/hindsight/commit/8364b9c5)) +- Allow claude-agent-sdk to install correctly on Linux/Docker environments. ([`3f31cbf5`](https://github.com/vectorize-io/hindsight/commit/3f31cbf5)) +- In LiteLLM mode, fall back to the last user message when no explicit hindsight query is provided. ([`5e8952c5`](https://github.com/vectorize-io/hindsight/commit/5e8952c5)) +- Fix non-atomic async operation creation to prevent inconsistent operation records. ([`94cf89b5`](https://github.com/vectorize-io/hindsight/commit/94cf89b5)) +- Prevent orphaned parent operations when a batch retain child fails unexpectedly. ([`43942455`](https://github.com/vectorize-io/hindsight/commit/43942455)) +- Fix failures for non-ASCII entity names by ensuring entity IDs are set correctly. ([`438ce98b`](https://github.com/vectorize-io/hindsight/commit/438ce98b)) +- Correctly store LLM facts labeled as "assistant" as "experience" in the database. ([`446c75f3`](https://github.com/vectorize-io/hindsight/commit/446c75f3)) + ## [0.4.19](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.19) **Features** diff --git a/hindsight-docs/static/img/blog/release0420.png b/hindsight-docs/static/img/blog/release0420.png new file mode 100644 index 00000000..9a5df5d9 Binary files /dev/null and b/hindsight-docs/static/img/blog/release0420.png differ