diff --git a/hindsight-api-slim/pyproject.toml b/hindsight-api-slim/pyproject.toml index 08541ea6a..e6a5e3d4d 100644 --- a/hindsight-api-slim/pyproject.toml +++ b/hindsight-api-slim/pyproject.toml @@ -40,7 +40,7 @@ dependencies = [ "anthropic>=0.40.0", "typer>=0.9.0", "cohere>=5.0.0", - "litellm>=1.0.0", + "litellm>=1.0.0,<=1.82.6", # 1.82.7+ contains a supply chain attack (malicious .pth credential stealer) "markitdown[pdf,docx,pptx,xlsx,xls]>=0.1.4", # File to markdown conversion "obstore>=0.4.0", # S3/GCS/Azure object storage client (Rust-backed) "uvloop>=0.22.1", diff --git a/hindsight-api-slim/tests/test_provider_default_models.py b/hindsight-api-slim/tests/test_provider_default_models.py index cc4241118..270553bdb 100644 --- a/hindsight-api-slim/tests/test_provider_default_models.py +++ b/hindsight-api-slim/tests/test_provider_default_models.py @@ -97,8 +97,8 @@ def test_per_operation_provider_default_model(): # Retain should use Anthropic default assert ( - config.retain_llm_model == "claude-haiku-4-5-20251001" - ), f"Expected claude-haiku-4-5-20251001, got {config.retain_llm_model}" + config.retain_llm_model == "claude-haiku-4-5" + ), f"Expected claude-haiku-4-5, got {config.retain_llm_model}" finally: clear_config_cache() diff --git a/hindsight-dev/hindsight_dev/generate_changelog.py b/hindsight-dev/hindsight_dev/generate_changelog.py index dfc0a8ae0..295c90d6d 100644 --- a/hindsight-dev/hindsight_dev/generate_changelog.py +++ b/hindsight-dev/hindsight_dev/generate_changelog.py @@ -28,7 +28,17 @@ CHANGELOG_PATH = REPO_PATH / "hindsight-docs" / "src" / "pages" / "changelog" / "index.md" INTEGRATION_CHANGELOG_DIR = REPO_PATH / "hindsight-docs" / "src" / "pages" / "changelog" / "integrations" -VALID_INTEGRATIONS = ["litellm", "pydantic-ai", "crewai", "ai-sdk", "chat", "openclaw", "langgraph", "nemoclaw", "strands"] +VALID_INTEGRATIONS = [ + "litellm", + "pydantic-ai", + "crewai", + "ai-sdk", + "chat", + "openclaw", + "langgraph", + "nemoclaw", + "strands", +] class ChangelogEntry(BaseModel): diff --git a/hindsight-integrations/litellm/pyproject.toml b/hindsight-integrations/litellm/pyproject.toml index 840019866..a43dd9870 100644 --- a/hindsight-integrations/litellm/pyproject.toml +++ b/hindsight-integrations/litellm/pyproject.toml @@ -32,7 +32,7 @@ classifiers = [ ] dependencies = [ - "litellm>=1.40.0", + "litellm>=1.40.0,<=1.82.6", # 1.82.7+ contains a supply chain attack (malicious .pth credential stealer) # Transitive dependency security fixes "aiohttp>=3.13.3", # Multiple DoS vulnerabilities "filelock>=3.20.3", # TOCTOU race condition diff --git a/skills/hindsight-docs/references/changelog/index.md b/skills/hindsight-docs/references/changelog/index.md index 64ba96d45..e33d01f69 100644 --- a/skills/hindsight-docs/references/changelog/index.md +++ b/skills/hindsight-docs/references/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/skills/hindsight-docs/references/changelog/integrations/strands.md b/skills/hindsight-docs/references/changelog/integrations/strands.md new file mode 100644 index 000000000..f0607117f --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/strands.md @@ -0,0 +1,17 @@ +--- +hide_table_of_contents: true +--- + +# Strands Integration Changelog + +Changelog for [`hindsight-strands`](https://pypi.org/project/hindsight-strands/). + +For the source code, see [`hindsight-integrations/strands`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/strands). + +← [Back to main changelog](../index.md) + +## [0.1.1](https://github.com/vectorize-io/hindsight/tree/integrations/strands/v0.1.1) + +**Features** + +- Added Strands Agents SDK integration, enabling Hindsight memory tools to be used with Strands agents. ([`7fe773c0`](https://github.com/vectorize-io/hindsight/commit/7fe773c0)) diff --git a/skills/hindsight-docs/references/openapi.json b/skills/hindsight-docs/references/openapi.json index 47171512c..866e5a7dd 100644 --- a/skills/hindsight-docs/references/openapi.json +++ b/skills/hindsight-docs/references/openapi.json @@ -10,7 +10,7 @@ "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "0.4.19" + "version": "0.4.20" }, "paths": { "/health": { diff --git a/skills/hindsight-docs/references/sdks/integrations/claude-code.md b/skills/hindsight-docs/references/sdks/integrations/claude-code.md index 846d4cbaf..70e6931a2 100644 --- a/skills/hindsight-docs/references/sdks/integrations/claude-code.md +++ b/skills/hindsight-docs/references/sdks/integrations/claude-code.md @@ -74,13 +74,15 @@ The plugin automatically starts and stops `hindsight-embed` via `uvx`. Requires Set an LLM provider: ```bash -export OPENAI_API_KEY="sk-your-key" # Auto-detected, uses gpt-4o-mini +export OPENAI_API_KEY="sk-your-key" # or -export ANTHROPIC_API_KEY="your-key" # Auto-detected, uses claude-3-5-haiku +export ANTHROPIC_API_KEY="your-key" # or export HINDSIGHT_LLM_PROVIDER=claude-code # No API key needed ``` +The model is selected automatically by the Hindsight API. To override, set `HINDSIGHT_API_LLM_MODEL`. + ### 3. Existing Local Server If you already have `hindsight-embed` running, leave `hindsightApiUrl` empty and set `apiPort` to match your server's port. The plugin will detect it automatically. diff --git a/skills/hindsight-docs/references/sdks/integrations/openclaw.md b/skills/hindsight-docs/references/sdks/integrations/openclaw.md index 609bc4f14..9fa83729d 100644 --- a/skills/hindsight-docs/references/sdks/integrations/openclaw.md +++ b/skills/hindsight-docs/references/sdks/integrations/openclaw.md @@ -17,22 +17,22 @@ This plugin integrates [hindsight-embed](https://vectorize.io/hindsight/cli), a Choose one provider and set its API key: ```bash -# Option A: OpenAI (uses gpt-4o-mini for memory extraction) +# Option A: OpenAI export OPENAI_API_KEY="sk-your-key" -# Option B: Anthropic (uses claude-3-5-haiku for memory extraction) +# Option B: Anthropic export ANTHROPIC_API_KEY="your-key" -# Option C: Gemini (uses gemini-2.5-flash for memory extraction) +# Option C: Gemini export GEMINI_API_KEY="your-key" -# Option D: Groq (uses openai/gpt-oss-20b for memory extraction) +# Option D: Groq export GROQ_API_KEY="your-key" -# Option E: Claude Code (uses claude-sonnet-4-20250514, no API key needed) +# Option E: Claude Code (no API key needed) export HINDSIGHT_API_LLM_PROVIDER=claude-code -# Option F: OpenAI Codex (uses gpt-4o-mini, no API key needed) +# Option F: OpenAI Codex (no API key needed) export HINDSIGHT_API_LLM_PROVIDER=openai-codex ``` @@ -161,20 +161,21 @@ By default, the plugin retains `user` and `assistant` messages after each turn. The plugin auto-detects your LLM provider from these environment variables: -| Provider | Env Var | Default Model | Notes | -|----------|---------|---------------|-------| -| OpenAI | `OPENAI_API_KEY` | `gpt-4o-mini` | | -| Anthropic | `ANTHROPIC_API_KEY` | `claude-3-5-haiku-20241022` | | -| Gemini | `GEMINI_API_KEY` | `gemini-2.5-flash` | | -| Groq | `GROQ_API_KEY` | `openai/gpt-oss-20b` | | -| Claude Code | `HINDSIGHT_API_LLM_PROVIDER=claude-code` | `claude-sonnet-4-20250514` | No API key needed | -| OpenAI Codex | `HINDSIGHT_API_LLM_PROVIDER=openai-codex` | `gpt-4o-mini` | No API key needed | +| Provider | Env Var | Notes | +|----------|---------|-------| +| OpenAI | `OPENAI_API_KEY` | | +| Anthropic | `ANTHROPIC_API_KEY` | | +| Gemini | `GEMINI_API_KEY` | | +| Groq | `GROQ_API_KEY` | | +| Claude Code | `HINDSIGHT_API_LLM_PROVIDER=claude-code` | No API key needed | +| OpenAI Codex | `HINDSIGHT_API_LLM_PROVIDER=openai-codex` | No API key needed | + +The model is selected automatically by the Hindsight API. To override, set `HINDSIGHT_API_LLM_MODEL`. **Override with explicit config:** ```bash export HINDSIGHT_API_LLM_PROVIDER=openai -export HINDSIGHT_API_LLM_MODEL=gpt-4o-mini export HINDSIGHT_API_LLM_API_KEY=sk-your-key # Optional: custom base URL (OpenRouter, Azure, vLLM, etc.) diff --git a/skills/hindsight-docs/references/sdks/integrations/strands.md b/skills/hindsight-docs/references/sdks/integrations/strands.md new file mode 100644 index 000000000..6ab422de8 --- /dev/null +++ b/skills/hindsight-docs/references/sdks/integrations/strands.md @@ -0,0 +1,155 @@ +--- +sidebar_position: 13 +--- + +# Strands Agents + +Persistent memory tools for [Strands Agents SDK](https://github.com/strands-agents/sdk-python) agents via Hindsight. Give your agents long-term memory with retain, recall, and reflect — using Strands' native `@tool` pattern. + +## Features + +- **Native `@tool` Functions** - Tools are plain Python functions, compatible with `Agent(tools=[...])` +- **Memory Instructions** - Pre-recall memories for injection into agent system prompt +- **Three Memory Tools** - Retain (store), Recall (search), Reflect (synthesize) — include any combination +- **Simple Configuration** - Configure once globally, or pass a client directly + +## Installation + +```bash +pip install hindsight-strands +``` + +## Quick Start + +```python +from strands import Agent +from hindsight_strands import create_hindsight_tools + +tools = create_hindsight_tools( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", +) + +agent = Agent(tools=tools) +agent("Remember that I prefer dark mode") +agent("What are my preferences?") +``` + +The agent now has three tools it can call: + +- **`hindsight_retain`** — Store information to long-term memory +- **`hindsight_recall`** — Search long-term memory for relevant facts +- **`hindsight_reflect`** — Synthesize a reasoned answer from memories + +## With Memory Instructions + +Pre-recall relevant memories and inject them into the system prompt: + +```python +from hindsight_strands import create_hindsight_tools, memory_instructions + +tools = create_hindsight_tools( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", +) + +memories = memory_instructions( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", +) + +agent = Agent( + tools=tools, + system_prompt=f"You are a helpful assistant.\n\n{memories}", +) +``` + +## Selecting Tools + +Include only the tools you need: + +```python +tools = create_hindsight_tools( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", + enable_retain=True, + enable_recall=True, + enable_reflect=False, # Omit reflect +) +``` + +## Global Configuration + +Instead of passing connection details to every call, configure once: + +```python +from hindsight_strands 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 connection details +tools = create_hindsight_tools(bank_id="user-123") +``` + +## Configuration Reference + +### `create_hindsight_tools()` + +| Parameter | Default | Description | +|---|---|---| +| `bank_id` | *required* | Hindsight memory bank ID | +| `client` | `None` | Pre-configured Hindsight client | +| `hindsight_api_url` | `None` | API URL (used if no client provided) | +| `api_key` | `None` | API key (used if no client provided) | +| `budget` | `"mid"` | Recall/reflect budget level (low/mid/high) | +| `max_tokens` | `4096` | Maximum tokens for recall results | +| `tags` | `None` | Tags applied when storing memories | +| `recall_tags` | `None` | Tags to filter when searching | +| `recall_tags_match` | `"any"` | Tag matching mode | +| `enable_retain` | `True` | Include the retain (store) tool | +| `enable_recall` | `True` | Include the recall (search) tool | +| `enable_reflect` | `True` | Include the reflect (synthesize) tool | + +### `memory_instructions()` + +| Parameter | Default | Description | +|---|---|---| +| `bank_id` | *required* | Hindsight memory bank ID | +| `client` | `None` | Pre-configured Hindsight client | +| `hindsight_api_url` | `None` | API URL (used if no client provided) | +| `api_key` | `None` | API key (used if no client provided) | +| `query` | `"relevant context about the user"` | Recall query for memory injection | +| `budget` | `"low"` | Recall budget level | +| `max_results` | `5` | Maximum memories to inject | +| `max_tokens` | `4096` | Maximum tokens for recall results | +| `prefix` | `"Relevant memories:\n"` | Text prepended before memory list | +| `tags` | `None` | Tags to filter recall results | +| `tags_match` | `"any"` | Tag matching mode | + +### `configure()` + +| Parameter | Default | Description | +|---|---|---| +| `hindsight_api_url` | Production API | Hindsight API URL | +| `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication | +| `budget` | `"mid"` | Default recall budget level | +| `max_tokens` | `4096` | Default max tokens for recall | +| `tags` | `None` | Default tags for retain operations | +| `recall_tags` | `None` | Default tags to filter recall | +| `recall_tags_match` | `"any"` | Default tag matching mode | +| `verbose` | `False` | Enable verbose logging | + +## Requirements + +- Python >= 3.10 +- strands-agents +- hindsight-client >= 0.4.0 +- A running Hindsight API server diff --git a/uv.lock b/uv.lock index e7abb137f..f8a144487 100644 --- a/uv.lock +++ b/uv.lock @@ -1627,7 +1627,7 @@ requires-dist = [ { name = "langchain-core", specifier = ">=1.2.11" }, { name = "langchain-text-splitters", specifier = ">=0.3.0" }, { name = "langsmith", specifier = ">=0.6.3" }, - { name = "litellm", specifier = ">=1.0.0" }, + { name = "litellm", specifier = ">=1.0.0,<=1.82.6" }, { name = "markitdown", extras = ["pdf", "docx", "pptx", "xlsx", "xls"], specifier = ">=0.1.4" }, { name = "mlx", marker = "extra == 'local-ml'", specifier = ">=0.31.0" }, { name = "mlx-lm", marker = "extra == 'local-ml'", specifier = ">=0.31.1" },