* docs: add Volcano Engine as supported LLM provider
Follow-up to #714. Add Volcano Engine (ByteDance) to the documentation:
- LLM providers grid component
- Provider list in configuration docs
- Provider example with base URL and default model
- Default model table in models page
* chore: regenerate docs skill references
Add 10 missing bank-configurable fields to update_bank_config():
- entity_labels, entities_allow_free_form
- consolidation_llm_batch_size, consolidation_source_facts_max_tokens,
consolidation_source_facts_max_tokens_per_observation
- retain_default_strategy, retain_strategies
- reflect_source_facts_max_tokens
- mcp_enabled_tools
- llm_gemini_safety_settings
Previously these could only be set via raw PATCH to /config.
All new params are keyword-only with None defaults (backwards compatible).
- Add 'ark' and 'volcano' as valid LLM providers (both are aliases for Volcano Engine)
- Set default model to 'doubao-pro-32k' for both providers
- Add them to OpenAICompatibleLLM provider list
- Exclude from json_object response format support
Co-authored-by: yishun.eason <yishun.eason@bytedance.com>
Add 10 missing bank-configurable fields to update_bank_config():
- entity_labels, entities_allow_free_form
- consolidation_llm_batch_size, consolidation_source_facts_max_tokens,
consolidation_source_facts_max_tokens_per_observation
- retain_default_strategy, retain_strategies
- reflect_source_facts_max_tokens
- mcp_enabled_tools
- llm_gemini_safety_settings
Previously these could only be set via raw PATCH to /config.
All new params are keyword-only with None defaults (backwards compatible).
* docs(python-client): improve pydoc strings for async-first usage and low-level API access
- Class docstring now clearly documents async-first pattern: a* methods
preferred, sync wrappers for scripts/REPLs only
- Every sync method docstring points to its async counterpart
- Every async method docstring says "preferred"
- Expose 10 low-level API properties (documents, entities, operations,
webhooks, monitoring, etc.) so agents/users can discover the full API
surface without guessing at _-prefixed internals
- Add missing API parameters: tag_groups (recall/reflect), fact_types,
exclude_mental_models, exclude_mental_model_ids (reflect),
observation_scopes/strategy (retain items), background (create_bank)
- Fix areflect missing include_facts param that sync reflect already had
- Sync recall/reflect now delegate to async counterparts (no logic duplication)
* style(retain): format long function call arguments one-per-line
* feat(openclaw): add recallInjectionPosition config to preserve prompt cache
Add configurable injection position for recalled memories to avoid
breaking prefix-based prompt caching (Anthropic/Google) when agents
have large static system prompts.
Options: 'prepend' (default, current behavior), 'append' (end of
system prompt, preserves cache), 'user' (before user message).
Closes#703
* docs(openclaw): document all plugin config flags
Add missing config options to the OpenClaw docs: recallTopK,
recallTypes, recallContextTurns, recallMaxQueryChars,
recallPromptPreamble, recallInjectionPosition, recallRoles,
retainEveryNTurns, retainOverlapTurns, and debug.
* docs(claude-code): tidy configuration reference and sync README
Add missing settings (retainMode, retainToolCalls, retainTags,
retainMetadata, embedPackagePath, llmApiKeyEnv, agentName, and
several recall options) that existed in code but not in docs.
Restructure config tables with prose introductions, clearer
descriptions, and consistent layout across both files.
* refactor(claude-code): remove recallTopK setting
Unused client-side cap — Hindsight server already controls result
count via recallBudget and recallMaxTokens.
* fix(python-client): async=true was silently ignored on retain calls
The hand-written client wrapper passed `async_=retain_async` to
RetainRequest, but the generated Pydantic model uses `var_async` as the
Python field name (with `alias="async"`). The `async_` kwarg didn't
match either the field name or the alias, so Pydantic silently ignored
it — every retain call ran synchronously regardless of the flag.
This has been broken since the client was first introduced (6073ac4f),
not a regression.
Also adds unit tests that verify the async field serializes correctly
in the request JSON, preventing future regressions.
* docs(claude-code): tidy configuration reference and sync README
Add missing settings (retainMode, retainToolCalls, retainTags,
retainMetadata, embedPackagePath, llmApiKeyEnv, agentName, and
several recall options) that existed in code but not in docs.
Restructure config tables with prose introductions, clearer
descriptions, and consistent layout across both files.
* refactor(claude-code): remove recallTopK setting
Unused client-side cap — Hindsight server already controls result
count via recallBudget and recallMaxTokens.
* feat(retain): delta retain — skip LLM re-extraction for unchanged chunks on upsert
When upserting a document (same document_id), instead of deleting all
facts and re-extracting from scratch, compare chunk content hashes
and only process changed/new chunks. Unchanged chunks keep their
existing facts, entities, and links.
- Add content_hash column to chunks table (migration b3c4d5e6f7a8)
- Add chunk delta comparison functions in chunk_storage.py
- Add delta_mode to fact_storage.handle_document_tracking (skip full delete)
- Add update_memory_units_tags for propagating tag changes to existing facts
- Refactor orchestrator into _try_delta_retain and _full_retain paths
- Automatic fallback to full retain for pre-migration data or all-changed scenarios
- Fix ty type error in metrics.py (resource module import on Windows)
- 16 new tests covering entities, links, tags, metadata, edge cases
* refactor(retain): deduplicate delta and full retain paths
Extract shared _insert_facts_and_links() and _extract_and_embed()
functions used by both the full retain and delta retain paths.
Remove delta_mode flag from handle_document_tracking — delta path
uses dedicated upsert_document_metadata() instead.
* chore: regenerate clients, openapi spec, and lockfile
* chore: regenerate docs skill
When retainToolCalls is enabled (new default), the retention transcript
is output as JSON with full message structure including tool_use blocks
(Edit, Read, Bash, Grep, etc.) and their complete input dicts, plus
tool_result blocks (truncated at 2k chars). This preserves the context
of what actions the assistant actually took, not just its narration.
Hindsight MCP tools (recall/retain/reflect) are excluded to prevent
feedback loops. Channel message tools still get their text extracted
inline. Setting retainToolCalls=false falls back to the legacy text
format.
* feat(claude-code): full-session retain mode with document upsert and configurable tags
Switch default retain behavior from per-turn chunks to full-session upsert.
Each session is now retained as a single document (document_id = session_id)
that gets updated on every Stop event, instead of creating fragmented
documents with timestamp-suffixed IDs.
New config options:
- retainMode: "full-session" (default) or "chunked" (legacy)
- retainTags: list with template variable support ({session_id}, {bank_id}, {timestamp})
- retainMetadata: extra metadata dict merged with built-in fields, supports templates
* fix(claude-code): respect retainEveryNTurns in full-session mode
The turn-count gating was only applied in chunked mode, meaning
full-session mode would re-ingest the entire transcript on every
single Stop event. Now retainEveryNTurns gates both modes.
Also fix test isolation: resolve ~/.hindsight/claude-code.json at
call time (not module load) so HOME override in tests works correctly.
* fix(claude-code): fix config tests after USER_CONFIG_PATH removal
Update tests to use HOME env var override instead of monkeypatching
the removed USER_CONFIG_PATH constant. Add autouse fixture to
TestLoadConfig to isolate all config tests from real user config
and HINDSIGHT_* env vars.
* docs: add supported platforms section and Windows installation guide
Adds a platform compatibility table (Linux, macOS, Windows) and a
dedicated Windows setup section with step-by-step instructions for
installing PostgreSQL + pgvector and running Hindsight natively.
Follows up on #699 which added Windows native support.
Also fixes a ty type-check error in metrics.py for the conditional
resource module import.
* chore: sync generated clients and lock file after #699
Regenerate client SDKs to pick up ValidationError model changes
and update uv.lock with platform-specific uvloop/winloop deps.
* docs: update Windows section — pg0 now supports Windows
pg0 v0.12.0 added Windows support, so embedded DB works everywhere.
Restructure Windows section to show simple install-and-run first,
with external PostgreSQL as an optional alternative.
* chore: sync generated docs skill and openapi references
FastAPI generates the ValidationError schema with only loc, msg, and
type, but Pydantic v2 actually returns input, ctx, and url as well.
Generated clients with strict JSON decoding (Go's DisallowUnknownFields)
cannot parse real 422 responses — the actual validation message gets
replaced by a confusing JSON decoding error.
- Patch the OpenAPI schema in create_app() to add input, ctx, url
- Regenerate spec and Go client
* feat: Windows native support — run Hindsight without Docker on Windows
Four compatibility fixes that allow Hindsight to run natively on Windows
with an external PostgreSQL + pgvector installation:
1. **pyproject.toml**: Conditional event loop dependency
- `winloop` on Windows (sys_platform == 'win32')
- `uvloop` on Linux/macOS (sys_platform != 'win32')
2. **main.py**: winloop integration via `winloop.install()`
- Patches asyncio event loop policy globally before uvicorn starts
- uvicorn sees "asyncio" but runs winloop underneath (same perf as uvloop)
- Falls back to default asyncio if winloop unavailable
3. **metrics.py**: Guard `resource` module import
- `resource` is Unix-only (getrusage, getrlimit)
- Conditional import with None fallback
- Skip process metrics collection on Windows
4. **fact_storage.py**: Cross-platform strftime
- `%-d` (no-padding day) is glibc-only, fails on Windows
- Replaced with `%d` + `.replace(" 0", " ")` for same output
## Windows Setup Guide
### Prerequisites
- Python 3.11+
- PostgreSQL 17 with pgvector extension
- Ollama (for local embeddings) or external embedding provider
### Install PostgreSQL + pgvector on Windows
```bash
winget install PostgreSQL.PostgreSQL.17
# Build pgvector from source (requires Visual Studio Build Tools)
git clone https://github.com/pgvector/pgvector.git
# In x64 Native Tools Command Prompt:
set PGROOT=C:\Program Files\PostgreSQL\17
nmake /F Makefile.win
nmake /F Makefile.win install
# Enable extension
psql -U postgres -d hindsight -c "CREATE EXTENSION IF NOT EXISTS vector;"
```
### Install and Run Hindsight
```bash
pip install -e ".[embedded-db]"
# Set environment variables
set HINDSIGHT_API_LLM_PROVIDER=openai
set HINDSIGHT_API_LLM_API_KEY=your-api-key
set HINDSIGHT_API_LLM_BASE_URL=https://your-llm-endpoint/v1
set HINDSIGHT_API_LLM_MODEL=your-model
set HINDSIGHT_API_DATABASE_URL=postgresql://postgres@localhost:5432/hindsight
set HINDSIGHT_API_EMBEDDING_PROVIDER=ollama
set HINDSIGHT_API_PORT=8889
hindsight-api
```
Data persists in PostgreSQL on your local disk — survives reboots,
updates, and anything that would wipe a Docker volume.
Tested on Windows 11 with PostgreSQL 17.9, pgvector 0.8.2,
Python 3.11, RTX 5080 (CUDA embeddings + reranking).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: handle strftime ValueError on Windows in fact_storage
The strftime call on occurred_start/occurred_end can raise ValueError
on Windows when the datetime object has unexpected format properties.
Wrap in try/except to gracefully skip date signal rather than crash
the entire retain batch.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: control plane UI fixes for recall and data view
- Sanitize NaN cross-encoder scores to 0.0 in reranking pipeline
(Pydantic serializes NaN as JSON null, breaking UI score display)
- Add null-coalesce for score in search debug view to prevent crash
- Switch data view text filter from debounced onChange to Enter key
(avoids slow ILIKE queries on every keystroke for large banks)
- Show loading spinner in search icon during filter requests
- Preserve search/tag filters when clicking "Load more"
* chore: sync generated files after rebase
fcntl is a Unix-only module — importing it unconditionally causes an
ImportError on Windows, breaking the entire plugin. Guard the import with a
sys.platform check and fall back to a no-op lock path in
increment_turn_count() so Windows users get correct behaviour without
crashing.
Adds a proper 'none' provider option so users can run Hindsight as a
chunk store with semantic search but without any LLM dependency, replacing
the hacky workaround of setting provider to 'mock'.
When HINDSIGHT_API_LLM_PROVIDER=none:
- Retain automatically uses chunks mode (no fact extraction)
- Recall works normally (semantic search, BM25, graph retrieval)
- Reflect returns HTTP 400 with clear error message
- Consolidation/observations are disabled
- Mental model refresh returns HTTP 400
- No API key required
* feat(reflect): make source facts in search_observations configurable
The recent fix (#669) hardcoded include_source_facts=False in
search_observations to prevent context overflow. This makes it
configurable via HINDSIGHT_API_REFLECT_SOURCE_FACTS_MAX_TOKENS
(env/tenant/bank), defaulting to -1 (disabled).
- -1: source facts disabled (current behavior, default)
- 0: source facts enabled with no token limit
- >0: source facts enabled with a token budget
* docs: add reflect_source_facts_max_tokens to configuration reference
* fix: update configurable fields count in tests and regenerate docs skill
Claude Code's plugin installer does not merge hooks.json into settings.json
automatically. This adds a setup script and skill that users can run once
after installing the plugin to register the hooks manually.
* feat(hermes): file-based config + updated docs
Replace the old dataclass/configure() singleton with a plain dict
config loaded from ~/.hindsight/hermes.json — same field names and
conventions as the openclaw and claude-code integrations.
Loading order: defaults → config file → env var overrides.
- config.py: rewritten with load_config() returning a plain dict,
DEFAULTS matching openclaw/claude-code fields, ENV_OVERRIDES with
typed casting
- tools.py: register() uses load_config() instead of raw env vars
- __init__.py: clean exports (removed configure/get_config/reset_config)
- README.md: full rewrite with config file examples, tables by category
- docs/hermes.md: full rewrite with quick start, architecture, all
config tables, gateway section, troubleshooting
- tests: updated for new config pattern, 46 tests pass
* ci: add test job for hermes integration
* chore: regenerate docs skill for hermes integration
Add a detect-changes job using dorny/paths-filter to determine which
parts of the monorepo changed, then gate each CI job with appropriate
conditions. This avoids running all ~30 jobs for docs-only or
integration-only changes.
Key behaviors:
- Docs/README-only changes only run build-docs and test-doc-examples
- Integration package changes only run their specific test job
- Client SDK changes only run their build/test + dependent jobs
- Core API changes run all API-dependent jobs
- CI config changes (.github/**) run everything as a safety net
- workflow_dispatch (manual) always runs everything
- verify-generated-files always runs unconditionally
* feat(embed): add programmatic UI (control plane) management
Add ability to start/stop the web UI from hindsight-embed, with
configurable port (default: daemon_port + 10000) and hostname
(default: 0.0.0.0). Uses npx to run the published control plane
package, or node directly in dev mode.
New CLI commands:
hindsight-embed ui start [--port PORT] [--hostname HOST]
hindsight-embed ui stop [--port PORT]
hindsight-embed ui status [--port PORT]
hindsight-embed ui logs [-f] [-n N]
New programmatic API:
daemon_client.start_ui(profile, ui_port, hostname)
daemon_client.stop_ui(profile, ui_port)
daemon_client.is_ui_running(profile, ui_port)
daemon_client.get_ui_url(profile, ui_port)
* feat(embed): expose UI management on HindsightEmbedded
Add start_ui(), stop_ui(), is_ui_running(), and ui_url property
to HindsightEmbedded so the UI can be started programmatically:
client = HindsightEmbedded(profile="myapp", ...)
client.start_ui() # starts daemon + UI
print(client.ui_url)
* feat: add LiteLLM LLM provider for Bedrock and 100+ providers
Add a new `litellm` LLM provider that uses the LiteLLM SDK for chat
completions and tool calling, enabling AWS Bedrock and 100+ other
providers for Hindsight's core engine (retain, recall, reflect).
- New LiteLLMLLM provider in engine/providers/litellm_llm.py
- Registered in factory, valid providers list, and no-api-key set
- Refactored API key validation to use requires_api_key() helper
- Added boto3 dependency for Bedrock auth
- Updated docs: configuration, models, monitoring, providers grid
* feat: add bedrock as first-class LLM provider alias
Add `bedrock` as a dedicated provider name that auto-prepends the
`bedrock/` prefix to model names and delegates to LiteLLMLLM under
the hood. This makes Bedrock support more discoverable — users set
`HINDSIGHT_API_LLM_PROVIDER=bedrock` with plain Bedrock model IDs.
* test: add Bedrock to CI provider tests
- Add bedrock/us.amazon.nova-lite-v1:0 to MODEL_MATRIX in test_llm_provider.py
- Add AWS credential check in should_skip_provider()
- Pass AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME secrets to test-api job
- Update default bedrock model to amazon.nova-2-lite-v1:0
* fix: regenerate docs skill files and bump memory test timeout
- Regenerate skills/hindsight-docs references after docs changes
- Bump test_llm_provider_memory_operations timeout to 600s for slower
providers like Bedrock via LiteLLM
* test: skip bedrock lite models in memory operations test
Nova Lite has a 10K output token limit which is too low for fact
extraction (requires 64K). The api_methods test (completion, tools,
structured output) already validates the provider works correctly.
* test: use Nova Pro for bedrock CI tests to cover full memory pipeline
Nova Lite only supports 10K output tokens, too low for fact extraction.
Switch to Nova Pro which supports the full 64K output needed for
retain/reflect operations. This ensures bedrock is tested on all
Hindsight functionalities, not just basic API methods.
* test: switch bedrock CI to Nova 2 Lite (supports 64K output tokens)
Nova v1 models (Pro, Lite) have a 10K output token limit which is
too low for fact extraction. Nova 2 Lite supports 64K+ output tokens,
enabling full memory pipeline testing (retain + reflect).
MCP tool bridges sometimes serialize JSON arrays as strings during
transport, e.g. '["a", "b"]' arrives as the literal string '["a", "b"]'
instead of a native JSON array. This causes Pydantic to reject the
input with a validation error.
Add defensive coercion at two layers:
1. HTTP API (http.py): Pydantic field_validator on MemoryItem.tags
with mode="before" that parses JSON strings back into lists.
2. MCP tools (mcp_tools.py): Same coercion in build_content_dict
before tags reach the Pydantic model.
A plain non-JSON string is wrapped in a single-element list.
Correctly-formatted input is passed through unchanged.
Co-authored-by: Philipp <philipp@Philipps-MacBook-Pro.local>
Expose the named retain strategy on the MCP retain tool, matching the
HTTP API's per-item strategy support. This allows MCP clients (Claude
Code, Claude Desktop, etc.) to specify extraction behavior per memory:
strategy: "exact" → verbatim storage, no LLM processing
strategy: "verbose" → detailed extraction
strategy: "concise" → default compressed extraction
Strategies are defined in bank config under retain_strategies.
Unknown strategy names are logged and ignored (bank default applies).
Changes:
- Add strategy param to both retain function signatures (with/without bank_id)
- Add strategy to build_content_dict
- Strategy is set in the content dict, which the engine already handles per-item
Co-authored-by: Philipp <philipp@Philipps-MacBook-Pro.local>
Tool handlers and lifecycle hooks now use the native async client API
(aretain, arecall, areflect, acreate_bank) instead of sync wrappers
that call loop.run_until_complete(), which deadlocks in async contexts
like Discord/Telegram gateways.
* fix: return metadata in recall responses (#674)
Metadata stored during retain was never retrieved during recall.
Add metadata to all SQL SELECT queries, the RetrievalResult dataclass,
ScoredResult.to_dict(), and MemoryFact construction in the recall pipeline.
* test: add metadata round-trip test for retain→recall
Replace placeholder metadata test with one that actually passes
metadata via retain_batch_async and asserts it is returned on recall.
* fix: parse metadata JSON string from database in MemoryFact
asyncpg may return JSONB columns as strings. Add a field_validator
to MemoryFact.metadata to handle JSON string deserialization.
* security: exclude litellm 1.82.8 (supply chain compromise)
litellm 1.82.8 on PyPI contains a malicious .pth file that
automatically steals credentials on Python startup (no import needed).
See: https://github.com/BerriAI/litellm/issues/24512
Our Docker images ship 1.82.6 and are unaffected, but the open version
constraints (>=1.0.0, >=1.40.0) would allow resolving to 1.82.8 on
fresh installs or lockfile refreshes.
* security: cap litellm at <=1.82.6 (1.82.7 also compromised)
* chore: regenerate uv.lock and openapi spec
* fix: update test to match claude-haiku-4-5 default model name and regenerate docs skill
* chore: fix ruff formatting in generate_changelog.py
* Add blog post: Adding Long-Term Memory to LangGraph and LangChain Agents
* blog: update langgraph post date to 2026-03-24 and add cover image
* blog: fix claude-code-telegram filename to match frontmatter date (2026-03-25)
* blog: set claude-code-telegram date to 2026-03-23
* blog: fix date timezone offset by adding T12:00 to all post dates
* ci: trigger fresh CI run
* blog: fix broken docs link (routeBasePath is /)
* feat: add Strands Agents SDK integration with Hindsight memory tools
* fix: add strands docs to versioned docs so build link check passes
* fix(strands): run hindsight client calls in thread pool to avoid event loop conflict with Strands
* feat(openclaw): remove hardcoded default models, rely on Hindsight API defaults
* feat(claude-code): remove hardcoded default models, rely on Hindsight API defaults
* feat(claude-code,docs): remove hardcoded default models from claude-code integration and docs
* feat: use claude-haiku-4-5 as default Anthropic model
* docs: add 0.4.20 release blog post and changelog
Add release notes blog post covering Claude Code integration, LangGraph
integration, NemoClaw integration, independent integration versioning,
and reflect improvements. Auto-generated changelog entry included.
* docs: add 0.4.20 release blog cover image
search_observations in the reflect agent hardcoded include_source_facts=True
with max_source_facts_tokens=-1 (unlimited). For banks with many observations
backed by thousands of facts, a single tool call could produce 300K+ tokens,
exceeding the default 100K context budget and causing forced synthesis with
an empty 'Retrieved Data' section.
The reflect agent synthesizes from observations, not raw backing facts.
Disable source facts to keep payloads proportional to observation count
(~6K vs ~310K in the reporter's case).
The consolidation path already has configurable source fact limits (PR #509,
v0.4.17). The reflect path was not updated.
Fixes#668
Co-authored-by: Kagura Chen <daniyuu19@sjtu.edu.cn>
