2d787c4ffd
* feat: add LlamaIndex integration for Hindsight
Add hindsight-llamaindex package providing persistent memory tools for
LlamaIndex agents via the native BaseToolSpec pattern. Includes retain,
recall, and reflect tools, a convenience factory, global config, full
test suite, docs page, blog post, and integrations.json entry.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address PR review feedback for llamaindex integration
- Fix ReActAgent API: from_tools() → constructor, chat() → await run()
- Add create_bank step to all quickstart examples
- Add production patterns section to docs (tags, error handling, bank lifecycle)
- Add memory scoping recommendation to README
- Add when-not-to-use section to blog post
- Add LlamaIndex compatibility tests (agent acceptance, FunctionTool.call)
- Fix self-hosted auth wording in cookbook notebook
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: use async client methods and asyncio.run() for runnable examples
- Use await client.acreate_bank() instead of sync create_bank() to
avoid "event loop already running" errors in notebooks and async contexts
- Wrap plain Python examples in async def main() + asyncio.run(main())
so they are copy-paste runnable as scripts
- Add Jupyter notebook tip to docs showing top-level await pattern
- Bank lifecycle example in docs now uses async acreate_bank
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add async tool methods to avoid event loop conflicts
HindsightToolSpec now provides both sync and async tool implementations
using LlamaIndex's (sync_fn, async_fn) tuple pattern in spec_functions.
Async agents (ReActAgent, etc.) use aretain/arecall/areflect natively,
avoiding the "Timeout context manager should be used inside a task"
error that occurred when sync _run_async() was called from within an
active event loop.
- Add aretain_memory, arecall_memory, areflect_on_memory async methods
- Extract shared kwargs builders (_retain_kwargs, _recall_kwargs, etc.)
- spec_functions now uses tuples: [("retain_memory", "aretain_memory"), ...]
- Tests verify tools have both sync fn and async fn set
- Notebook verified end-to-end with nbclient against local Hindsight
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove blog post from integration PR
The blog post will be pulled in separately from its own PR.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Address PR review: add context label, document_id auto-gen, bank mission, graceful errors
- Add `retain_context` param (default: "llamaindex") as source label on retain ops
- Auto-generate `document_id` as `{session_id}-{timestamp_ms}` when not provided
- Add `retain_async` param (default: True) for non-blocking retain processing
- Add `mission` param for automatic bank creation/management on first use
- Change error handling from raising HindsightError to graceful log + return message
- Add per-operation timeout constants in _client.py
- Add `context` and `mission` fields to config.py and configure()
- Update docs: document as standalone package (not LlamaHub), new params, patterns
- Tests: 51 passing (up from 34), covering all new features
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Restructure to LlamaIndex namespace packages + add BaseMemory implementation
Tools package (llama-index-tools-hindsight):
- Restructured from hindsight_llamaindex/ to llama_index/tools/hindsight/
- Import: from llama_index.tools.hindsight import HindsightToolSpec
- Follows PEP 420 implicit namespace package convention
- Removed retain_async param (client.retain() doesn't support async_processing)
Memory package (llama-index-memory-hindsight):
- New package: llama_index/memory/hindsight/
- HindsightMemory(BaseMemory) for automatic memory
- put() auto-retains user/assistant messages to Hindsight
- get(input) auto-recalls relevant memories, prepends as system message
- Graceful error handling, bank mission management, document_id generation
- 28 unit tests passing
Both packages follow LlamaIndex community conventions for future LlamaHub submission.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
44 lines
1.4 KiB
Markdown
44 lines
1.4 KiB
Markdown
# llama-index-memory-hindsight
|
|
|
|
Automatic long-term memory for LlamaIndex agents via [Hindsight](https://github.com/vectorize-io/hindsight).
|
|
|
|
Implements LlamaIndex's `BaseMemory` interface:
|
|
- **`put()`** — automatically retains user/assistant messages to Hindsight
|
|
- **`get()`** — recalls relevant memories and injects them as context
|
|
- **`reset()`** — clears the local chat buffer
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install llama-index-memory-hindsight
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
from hindsight_client import Hindsight
|
|
from llama_index.memory.hindsight import HindsightMemory
|
|
from llama_index.core.agent import ReActAgent
|
|
from llama_index.llms.openai import OpenAI
|
|
|
|
client = Hindsight(base_url="http://localhost:8888")
|
|
memory = HindsightMemory.from_client(
|
|
client=client,
|
|
bank_id="user-123",
|
|
mission="Track user preferences and project context",
|
|
)
|
|
|
|
agent = ReActAgent(tools=tools, llm=OpenAI(model="gpt-4o"), memory=memory)
|
|
```
|
|
|
|
## How It Works
|
|
|
|
- When the agent receives a message, `get(input)` recalls relevant memories from Hindsight and prepends them as a system message
|
|
- When the agent produces output, `put(message)` stores the conversation turn in Hindsight for future recall
|
|
- Chat history is kept in a local buffer for the current session; Hindsight provides cross-session persistence
|
|
|
|
## Requirements
|
|
|
|
- Python 3.10+
|
|
- `llama-index-core >= 0.11.0`
|
|
- `hindsight-client >= 0.4.0`
|