* doc: introduce mental models blog post
Write blog post introducing Mental Models in Hindsight 0.4.0:
- Evolution from observations and opinions
- How mental models work (consolidation, evidence tracking)
- Breaking changes and migration path
- Environment variable to enable (experimental)
- Agentic reflect explanation
* updates
* Update 2026-01-26-learning-capabilities.md
* fix: doc build issues
- Add missing code snippets for versioned docs (recall-opinions-only, recall-include-entities, bank-background)
- Fix broken links by using relative paths for version compatibility
- Update blog post title to sentence case
- Clear versions.json since v0.3 versioned docs don't exist yet
- Enable INCLUDE_CURRENT_VERSION in build script
* fix: update doc links after rebase
- Fix blog post to link to correct pages (/developer/api/mental-models and /developer/observations)
- Fix CLI docs to link to /api-reference instead of /api
* feat: add directives section to blog post
- Update intro to mention three layers of knowledge
- Add concise Directives section for compliance/guardrails
- Add directives to resources section
- Keep focus on learning capabilities (observations and mental models)
* fix: revert intro to focus on learning capabilities only
Directives are a separate feature for compliance/guardrails, not a learning capability. The blog post is about observations and mental models.
* fix: misc fixes for observations and mental models
* feat: improve graph retrieval for observations
- Update LinkExpansionRetriever to traverse through source_memory_ids
for observation entity connections (avoiding data duplication)
- Remove entity link copy from world facts to observations in consolidator
- Add tests for link expansion graph retrieval
- Add directives_applied field to ReflectResult
- Include user's other changes (CLI, docs, client updates)
* fix: CI test failures
- Add mental_model_id parameter to create_mental_model function
- Fix ToolCallTrace not including reason field from ToolCall
- Improve test_link_expansion_observation_graph_retrieval to wait for consolidation with retry
* chore: reduce link expansion log verbosity
* Revert "chore: reduce link expansion log verbosity"
This reverts commit 3ce759391cead1012157785fa78fef16ef9bfe3b.
* feat: add semantic/temporal/entity links as fallback in graph retrieval
- Add fallback query for semantic, temporal, and entity links from memory_links
- Check both directions (outgoing and incoming links)
- Weight fallback results at 0.5x to prioritize entity links via unit_entities
- Fixes graph retrieval returning 0 when data has cross-cluster temporal connections
* fix: enable observations fixture for link expansion test
- Add enable_observations fixture to ensure observations are created
- Increase wait time from 10 to 30 seconds for CI reliability
* feat(litellm): async retain with sync option, fix client session cleanup
- Add sync parameter to retain() for blocking vs background operation
- Default to async retain (sync=False) for better performance
- Add get_pending_retain_errors() to check async failures
- Fix "Unclosed client session" warnings by properly closing clients
- Fix "Timeout context manager" asyncio errors by creating fresh clients
- Each API call now creates and closes its own client (aiohttp limitation)
- Add _get_client() and _close_client() helpers for consistent handling
- Update recall(), reflect(), _retain_sync() and _inject_memories()
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(litellm): add reflect support and require explicit hindsight_query
- Make hindsight_query required when inject_memories=True to enforce
intentional memory queries (no automatic last-user-message fallback)
- Add reflect_context parameter for shaping LLM reasoning in reflect
- Add reflect_response_schema for structured JSON output from reflect
- Add _reflect_sync() and _reflect_async() methods in callbacks
- Update wrappers.py to support response_schema in reflect/areflect
This improves the developer experience by making memory injection
explicit and adds full reflect API support through the integration.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(litellm): rename recall_budget to budget, add per-call reflect context
- Rename `recall_budget` parameter to `budget` for consistency with API
- Add `hindsight_reflect_context` kwarg for per-call reflect context override
- Fix reflect() to not pass None values for optional parameters
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs(litellm): update README for new API structure and features
- Document configure() vs set_defaults() separation
- Add hindsight_query requirement when inject_memories=True
- Document async retain (sync=False default) and get_pending_retain_errors()
- Add hindsight_reflect_context per-call override documentation
- Document budget parameter (renamed from recall_budget)
- Add reflect_context and reflect_response_schema options
- Update all code examples to use new API structure
- Add new functions to API Reference table
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test(litellm): update tests for new configure/set_defaults API
- Update tests to use separate configure() and set_defaults() calls
- Fix test assertions to check config vs defaults appropriately
- Add tests for legacy parameter backwards compatibility
- Add new TestSetDefaults test class
- Fix _format_memories test call signature (settings, config order)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add set_bank_mission(), deprecate set_bank_background()
- Add mission parameter to hindsight_client.create_bank()
- Add set_bank_mission() function to hindsight_litellm
- Deprecate set_bank_background() with DeprecationWarning
- Update _create_or_update_bank() to support mission parameter
- Update README and docstrings to document the new API
The 'background' field has been deprecated in the Hindsight API in favor
of 'mission' which is used for mental model generation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Remove deprecated background parameter and legacy configure() parameters
- Remove set_bank_background() in favor of set_bank_mission()
- Remove background parameter from _create_or_update_bank()
- Remove background parameter from hindsight_client.create_bank()
- Remove legacy parameters from configure() (bank_id, document_id, budget, etc.)
- These have been replaced by the set_defaults() API
- Remove legacy test cases for deprecated parameters
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: update tests and docs to use mission instead of background
The create_bank() parameter was renamed from background to mission.
Update all tests and doc examples to use the new parameter name.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Nicolò Boschi <boschi1997@gmail.com>
* Fix main-methods.py: entities is a dict, use .items() and .canonical_name
* Migrate docs to use CodeSnippet components
- Convert quickstart.md, retain.md, recall.md, reflect.md, memory-banks.md to .mdx
- Use CodeSnippet to pull code from validated example scripts
- Add missing 'name' parameter to create_bank calls
- Fix main-methods.py entities iteration (dict not list)
- Remove retain-new.mdx demo file
* Migrate existing docs to match testing pattern with code snippet and add CLI tests to the CI
* Fix doc-id issue + add main-method tests
* CLI fixes
* Update openAPI json
* Fix rust build issues
* increase sleep time for Hindsight to process the document
* Added a polling sleep instead of fixed
* Delete immediately fails, so create the doc a earlier in the test to get the doc ready
* Add debug logs
* Remove debug logs
* Add documentation code validation system
- Create runnable example scripts in examples/api/ (19 files)
- Add CodeSnippet component for extracting marked sections
- Add raw-loader dependency for importing source files
- Create sample retain-new.mdx showing new approach
- Add README documenting coverage and gaps
* Fix wheel glob expansion in test-doc-examples CI job
* Fix CI issue
* Fix wheel path - uv build outputs to repo root dist/
* Fix: use explicit shell expansion for wheel install
* Fix: run cd in subshell so install runs from repo root
* Add documentation code validation CI job
- Use uv sync + uv run pattern (matches existing CI)
- Add requests to test dependencies for cleanup scripts
* Fix async API client usage in documents.py example
* Fix main-methods.py: RecallResult and ReflectFact don't have weight attribute
* Fix opinions.py: use actual API attributes instead of non-existent ones
* Fix example scripts: remove non-existent API attributes
- recall.py: remove .weight, fix entities iteration (dict not list)
- retain.mjs: remove result.async check
