mirror of
https://github.com/vectorize-io/hindsight.git
synced 2026-09-14 19:31:49 +08:00
Chris Bartholomew
5e71494702
nltk 3.10.0 is covered by a batch of advisories, the most serious of them critical, all patched in 3.10.3. nltk is purely transitive in both subprojects — neither declares it. It arrives via llama-index-core 0.14.21 (`nltk>=3.9.3`) and pipecat-ai 1.4.0 (`nltk>=3.9.4,<4`). Both ranges already admit 3.10.3, so this is a scoped `uv lock --upgrade-package nltk` with no manifest change and no parent-package bump. The resulting diff is nltk and nothing else: 8 lines in the llamaindex lock and 6 in pipecat. One of the llamaindex lines is unrelated to the bump — a newer uv writes a `python_full_version < '3.11'` marker on an exceptiongroup dependency edge that the lock was previously missing. Verified by reproducing the CI steps for both subprojects (`uv build`, `uv sync --frozen`, `uv run pytest tests`) with 3.10.3 installed: llamaindex 92 passed, pipecat 19 passed / 1 skipped. `uv lock --check` clean for both.
Hindsight Pipecat Integration
Persistent long-term memory for Pipecat voice AI pipelines via Hindsight. A single FrameProcessor slots between your user context aggregator and LLM service — recalling relevant memories before each turn and retaining conversation content after.
Quick Start
pip install hindsight-pipecat
✨ Recommended: Hindsight Cloud — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
from pipecat.pipeline.pipeline import Pipeline
from hindsight_pipecat import HindsightMemoryService
memory = HindsightMemoryService(
bank_id="user-123",
hindsight_api_url="https://api.hindsight.vectorize.io",
api_key="hsk_...", # or set HINDSIGHT_API_KEY env var
)
pipeline = Pipeline([
transport.input(),
stt_service,
user_aggregator,
memory, # ← add between user_aggregator and LLM
llm_service,
assistant_aggregator,
tts_service,
transport.output(),
])
Self-hosting (local development)
If you're running Hindsight locally with ./scripts/dev/start-api.sh, point at your local server instead:
memory = HindsightMemoryService(
bank_id="user-123",
hindsight_api_url="http://localhost:8888",
)
See the Hindsight installation guide for self-hosting setup.
How It Works
New turn starts
└─ LLMContextFrame arrives
├─ Retain previous complete turn (user+assistant) — fire-and-forget
└─ Recall relevant memories for current user query
└─ Inject as <hindsight_memories> system message
└─ Forward enriched context to LLM
On each LLMContextFrame:
- Retain — any new complete user+assistant turn pairs are sent to Hindsight asynchronously (non-blocking)
- Recall — the latest user message is used as the search query; results are injected as a system message before the LLM sees the context
- Forward — the enriched context frame is pushed downstream
Memory accumulates across calls. By the third or fourth turn, recall starts surfacing useful context that the pipeline didn't have to re-establish.
Prerequisites
A running Hindsight instance:
Self-hosted:
pip install hindsight-all
export HINDSIGHT_API_LLM_API_KEY=your-api-key
hindsight-api # starts on http://localhost:8888
Hindsight Cloud: Sign up — no self-hosting required.
Configuration
HindsightMemoryService(
bank_id="user-123", # Required: memory bank to use
hindsight_api_url="...", # Hindsight API URL
api_key="hsk_...", # API key (Hindsight Cloud)
recall_budget="mid", # "low", "mid", or "high"
recall_max_tokens=4096, # Max tokens for recall results
enable_recall=True, # Inject memories before LLM
enable_retain=True, # Store turns after each exchange
memory_prefix="Relevant memories from past conversations:\n",
)
Global configuration
from hindsight_pipecat import configure
configure(
hindsight_api_url="https://api.hindsight.vectorize.io", # Hindsight Cloud (default)
api_key="hsk_...",
recall_budget="mid",
)
# Now create services without repeating connection details
memory = HindsightMemoryService(bank_id="user-123")
Running Tests
pip install pytest pytest-asyncio
pytest tests/ -v