hindsight-livekit 0.1.0__tar.gz

hindsight_livekit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.1.0) is pushed, using PyPI
+# Trusted Publishing: no API token is stored in the repo.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Check the tag matches the package version
+        run: test "v$(uvx --from toml-cli toml get --toml-path pyproject.toml project.version)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - run: uv publish --trusted-publishing always

hindsight_livekit-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,42 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Oldest supported versions
+          - python: "3.11"
+            deps: "livekit-agents==1.2.0 hindsight-client==0.6.0"
+          # Latest versions
+          - python: "3.12"
+            deps: ""
+          - python: "3.14"
+            deps: ""
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Lint
+        run: |
+          uvx ruff check .
+          uvx ruff format --check .
+      - name: Test
+        run: |
+          uv venv --python ${{ matrix.python }}
+          # LiveKit 1.2-1.5 import httpx without declaring it
+          uv pip install -e . httpx pytest pytest-asyncio ${{ matrix.deps }}
+          uv run --no-sync pytest tests -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build

hindsight_livekit-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.env
+.env.local
+.pytest_cache/
+.ruff_cache/

hindsight_livekit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hindsight_livekit-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: hindsight-livekit
+Version: 0.1.0
+Summary: LiveKit Agents integration for Hindsight - persistent memory for voice AI agents
+Project-URL: Homepage, https://github.com/namandidthis/hindsight-livekit
+Project-URL: Repository, https://github.com/namandidthis/hindsight-livekit
+Project-URL: Issues, https://github.com/namandidthis/hindsight-livekit/issues
+Project-URL: Hindsight, https://github.com/vectorize-io/hindsight
+Author-email: Naman <naman6176@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,hindsight,livekit,memory,realtime,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: hindsight-client>=0.6.0
+Requires-Dist: livekit-agents<2.0,>=1.2
+Description-Content-Type: text/markdown
+
+# Hindsight LiveKit Integration
+
+Persistent long-term memory for [LiveKit Agents](https://github.com/livekit/agents) voice AI via [Hindsight](https://vectorize.io/hindsight). Your agent knows what it learned in earlier calls, and stores each new conversation as it happens. Works with STT-LLM-TTS pipelines and realtime (speech-to-speech) models.
+
+## Quick Start
+
+```bash
+pip install hindsight-livekit
+# or the latest from GitHub:
+pip install git+https://github.com/namandidthis/hindsight-livekit
+```
+
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
+```python
+from livekit.agents import AgentServer, AgentSession, JobContext, inference
+from hindsight_livekit import HindsightAgent, HindsightMemory
+
+server = AgentServer()
+
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext):
+    session = AgentSession(stt=..., tts=...)
+
+    memory = HindsightMemory(
+        bank_id="user-123",                    # one memory bank per end user
+        document_id=ctx.room.name,             # one transcript per call
+        hindsight_api_url="https://api.hindsight.vectorize.io",
+        api_key="hsk_...",                     # or set HINDSIGHT_API_KEY
+    )
+    memory.attach(session)                     # retain the conversation
+    ctx.add_shutdown_callback(memory.aclose)   # store the end of the call on hang-up
+
+    await session.start(
+        agent=HindsightAgent(
+            memory=memory,
+            llm=inference.LLM(model="google/gemma-4-31b-it"),
+            instructions="You are a friendly voice assistant.",
+        ),
+        room=ctx.room,
+    )
+    await ctx.connect()
+```
+
+`HindsightAgent` is a regular LiveKit `Agent`: subclass it, add `@function_tool`s, override `on_enter` (call `await super().on_enter()` first), and so on.
+
+Runnable agents built on [agent-starter-python](https://github.com/livekit-examples/agent-starter-python):
+
+- [`examples/voice_agent.py`](./examples/voice_agent.py) — STT-LLM-TTS pipeline
+- [`examples/realtime_agent.py`](./examples/realtime_agent.py) — realtime model with memory tools
+
+### Self-hosting (local development)
+
+```bash
+docker run --rm -p 8888:8888 -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY ghcr.io/vectorize-io/hindsight:latest
+```
+
+```python
+memory = HindsightMemory(bank_id="user-123", hindsight_api_url="http://localhost:8888")
+```
+
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for other options. LiveKit itself can be [self-hosted](https://docs.livekit.io/transport/self-hosting/local/) too; the integration works the same either way.
+
+## How It Works
+
+```
+memory.attach(session)
+  └─ Session recall starts: "who is this user?"  (overlaps with session.start)
+
+Agent starts (on_enter)
+  └─ Known facts about the user are added to the agent's instructions
+
+Before each LLM reply (llm_node)                       — STT-LLM-TTS pipelines only
+  └─ Recall memories relevant to the user's latest message
+       └─ Insert them before that message, in a copy of the chat context
+
+As the conversation happens (conversation_item_added)
+  └─ Append "User (time): …" / "Assistant (time): …" lines to the call's Hindsight document
+```
+
+| | STT-LLM-TTS pipeline | Realtime model |
+|---|---|---|
+| Recall when the agent starts | ✅ | ✅ |
+| Recall before each reply | ✅ | — (no step before a realtime reply; use the tools) |
+| Memory tools (`create_hindsight_tools`) | ✅ | ✅ |
+| Retain the conversation | ✅ | ✅ (needs the model's input audio transcription for the user's side) |
+
+**Session recall** runs once per call. `attach()` starts it, so it overlaps with LiveKit connecting the room and the model, and `HindsightAgent.on_enter` adds the result to the instructions. LiveKit runs `on_enter` in the background, so with a pipeline the first `llm_node` call also waits for the lookup and uses the instructions with memories, even if the user speaks first. A realtime model has no such step: a reply that starts before the lookup finishes (bounded by `recall_timeout`) won't include those memories, which is rare in practice since the lookup starts before the call connects.
+
+**Per-turn recall** runs in [`llm_node`](https://docs.livekit.io/agents/build/nodes/), the step every LLM call in a pipeline goes through. That means:
+
+- It works for spoken turns, chat text input and `session.generate_reply(user_input=...)`. The `on_user_turn_completed` hook only runs for spoken turns.
+- It works with [preemptive generation](https://docs.livekit.io/agents/build/audio/#preemptive-generation): recall starts while LiveKit is still confirming the end of the user's turn, and the preemptive reply is kept. Editing the context in `on_user_turn_completed` would make LiveKit discard it.
+- Memories are only added to a copy of the context for that call, so they never pile up in the session history. When the LLM calls a tool, the follow-up call reuses the same recall result.
+
+As in LiveKit's [RAG example](https://docs.livekit.io/agents/build/external-data/), per-turn memories are added as an `assistant` message just before the user's message, wrapped in `<hindsight_memories>` tags with a note telling the model not to read them out.
+
+**Retain** follows Hindsight's [guidance for conversations](https://hindsight.vectorize.io/developer/api/retain#retaining-a-conversation): each call is one document (`document_id`), written as `Name (timestamp): text` lines, grown with [`update_mode="append"`](https://hindsight.vectorize.io/developer/api/retain#update_mode) so Hindsight only extracts facts from the new part. Lines are sent once both the user and the agent have spoken, sorted by time, because realtime models can deliver the user's transcript after the reply it prompted. Appends are sent one at a time, in order, in the background, so they never delay a reply. `aclose()` sends whatever is left when the call ends.
+
+**Failures never break the call.** If recall fails or takes longer than `recall_timeout`, the agent carries on without memories. If retain fails, the error is logged.
+
+## Memory Tools
+
+`create_hindsight_tools()` gives the model `hindsight_retain`, `hindsight_recall` and `hindsight_reflect` tools, like the other Hindsight framework integrations. They are the way for a realtime model to look things up mid-call, and work with pipelines too:
+
+```python
+from hindsight_livekit import HindsightAgent, create_hindsight_tools
+
+agent = HindsightAgent(
+    memory=memory,
+    llm=inference.RealtimeModel(model="openai/gpt-realtime-mini"),
+    tools=create_hindsight_tools(bank_id=memory.bank_id, client=memory.client, include_reflect=False),
+    instructions=(
+        "You have long-term memory of past calls. When the user asks about themselves, "
+        "their past, or their preferences, call hindsight_recall first. When they share "
+        "something worth remembering, call hindsight_retain."
+    ),
+)
+```
+
+Tell the model when to use the tools, as above: models call them far more reliably with explicit guidance. `hindsight_reflect` runs an LLM on the Hindsight server, so it is the slowest; leave it out for snappier calls. Tool errors are raised as LiveKit `ToolError`, so the model hears what went wrong and can tell the caller.
+
+## Latency
+
+Recall happens while a caller waits, so the defaults are tuned for voice:
+
+- `recall_budget="low"`: Hindsight's [fast lookup](https://hindsight.vectorize.io/developer/api/recall#budget) setting.
+- `recall_max_tokens=1024`: keeps the prompt small.
+- `recall_timeout=3.0`: the longest a reply waits on memory before going ahead without it.
+
+With preemptive generation turned on, most per-turn recall time overlaps with end-of-turn detection.
+
+## Configuration
+
+```python
+HindsightMemory(
+    bank_id="user-123",                  # Required: memory bank to use
+    client=None,                         # Pre-built hindsight_client.Hindsight (optional)
+    hindsight_api_url="...",             # Defaults to HINDSIGHT_API_URL, then Hindsight Cloud
+    api_key="hsk_...",                   # Defaults to HINDSIGHT_API_KEY
+    document_id=None,                    # Defaults to a random "livekit-<uuid>"
+    recall_budget="low",                 # "low", "mid", or "high"
+    recall_max_tokens=1024,              # Max tokens of memories per recall
+    recall_timeout=3.0,                  # Seconds before carrying on without memories
+    recall_types=None,                   # e.g. ["world", "experience"]; None = all
+    tags=None,                           # Tags for retained content
+    recall_tags=None,                    # Tags to filter recall by
+    recall_tags_match="any",             # "any", "all", "any_strict", "all_strict"
+    retain_context="voice conversation", # Source label that guides fact extraction
+    user_name="User",                    # Speaker labels in the stored transcript
+    agent_name="Assistant",
+    enable_session_recall=True,          # Recall known facts when the agent starts
+    session_recall_query="Who is this user? ...",
+    enable_recall=True,                  # Recall before each reply (pipelines)
+    enable_retain=True,                  # Store the conversation
+)
+```
+
+### Global configuration
+
+```python
+from hindsight_livekit import configure
+
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+    recall_budget="low",
+)
+
+memory = HindsightMemory(bank_id="user-123")
+```
+
+### Using your own `Agent` or `llm_node`
+
+`memory.attach(session)` works with any `Agent`. To add recall to an agent that already overrides `llm_node` or `on_enter`, call the memory directly instead of subclassing `HindsightAgent`:
+
+```python
+from livekit.agents import Agent
+
+class MyAgent(Agent):
+    def __init__(self, memory: HindsightMemory) -> None:
+        super().__init__(instructions="...")
+        self.memory = memory
+
+    async def on_enter(self):
+        if memories := await self.memory.recall_session_context():
+            await self.update_instructions(f"{self.instructions}\n\n{memories}")
+
+    async def llm_node(self, chat_ctx, tools, model_settings):
+        chat_ctx = await self.memory.inject_memories(chat_ctx)
+        async for chunk in Agent.default.llm_node(self, chat_ctx, tools, model_settings):
+            yield chunk
+```
+
+## Prerequisites
+
+- `livekit-agents` 1.2 or later
+- A running Hindsight instance, self-hosted or [Hindsight Cloud](https://ui.hindsight.vectorize.io)
+
+## Running Tests
+
+```bash
+uv sync
+uv run pytest tests -v
+```
+
+The unit tests run a real LiveKit `AgentSession` with a scripted LLM and a mocked Hindsight client. The live tests in `tests/test_live_integration.py` run against a real Hindsight server when `HINDSIGHT_API_URL` is set, and also against real pipeline and realtime models through LiveKit Inference when LiveKit Cloud credentials are set:
+
+```bash
+docker run --rm -p 8888:8888 -e HINDSIGHT_API_LLM_PROVIDER=none ghcr.io/vectorize-io/hindsight:latest
+HINDSIGHT_API_URL=http://localhost:8888 uv run pytest tests -v
+
+# optional: real models via LiveKit Inference
+LIVEKIT_URL=wss://... LIVEKIT_API_KEY=... LIVEKIT_API_SECRET=... HINDSIGHT_API_URL=http://localhost:8888 uv run pytest tests -v
+```

hindsight_livekit-0.1.0/README.md

@@ -0,0 +1,216 @@
+# Hindsight LiveKit Integration
+
+Persistent long-term memory for [LiveKit Agents](https://github.com/livekit/agents) voice AI via [Hindsight](https://vectorize.io/hindsight). Your agent knows what it learned in earlier calls, and stores each new conversation as it happens. Works with STT-LLM-TTS pipelines and realtime (speech-to-speech) models.
+
+## Quick Start
+
+```bash
+pip install hindsight-livekit
+# or the latest from GitHub:
+pip install git+https://github.com/namandidthis/hindsight-livekit
+```
+
+> ✨ **Recommended: [Hindsight Cloud](https://ui.hindsight.vectorize.io)** — free tier, no self-hosting required. Sign up and grab an API key in under a minute.
+
+```python
+from livekit.agents import AgentServer, AgentSession, JobContext, inference
+from hindsight_livekit import HindsightAgent, HindsightMemory
+
+server = AgentServer()
+
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext):
+    session = AgentSession(stt=..., tts=...)
+
+    memory = HindsightMemory(
+        bank_id="user-123",                    # one memory bank per end user
+        document_id=ctx.room.name,             # one transcript per call
+        hindsight_api_url="https://api.hindsight.vectorize.io",
+        api_key="hsk_...",                     # or set HINDSIGHT_API_KEY
+    )
+    memory.attach(session)                     # retain the conversation
+    ctx.add_shutdown_callback(memory.aclose)   # store the end of the call on hang-up
+
+    await session.start(
+        agent=HindsightAgent(
+            memory=memory,
+            llm=inference.LLM(model="google/gemma-4-31b-it"),
+            instructions="You are a friendly voice assistant.",
+        ),
+        room=ctx.room,
+    )
+    await ctx.connect()
+```
+
+`HindsightAgent` is a regular LiveKit `Agent`: subclass it, add `@function_tool`s, override `on_enter` (call `await super().on_enter()` first), and so on.
+
+Runnable agents built on [agent-starter-python](https://github.com/livekit-examples/agent-starter-python):
+
+- [`examples/voice_agent.py`](./examples/voice_agent.py) — STT-LLM-TTS pipeline
+- [`examples/realtime_agent.py`](./examples/realtime_agent.py) — realtime model with memory tools
+
+### Self-hosting (local development)
+
+```bash
+docker run --rm -p 8888:8888 -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY ghcr.io/vectorize-io/hindsight:latest
+```
+
+```python
+memory = HindsightMemory(bank_id="user-123", hindsight_api_url="http://localhost:8888")
+```
+
+See the [Hindsight installation guide](https://hindsight.vectorize.io/developer/installation) for other options. LiveKit itself can be [self-hosted](https://docs.livekit.io/transport/self-hosting/local/) too; the integration works the same either way.
+
+## How It Works
+
+```
+memory.attach(session)
+  └─ Session recall starts: "who is this user?"  (overlaps with session.start)
+
+Agent starts (on_enter)
+  └─ Known facts about the user are added to the agent's instructions
+
+Before each LLM reply (llm_node)                       — STT-LLM-TTS pipelines only
+  └─ Recall memories relevant to the user's latest message
+       └─ Insert them before that message, in a copy of the chat context
+
+As the conversation happens (conversation_item_added)
+  └─ Append "User (time): …" / "Assistant (time): …" lines to the call's Hindsight document
+```
+
+| | STT-LLM-TTS pipeline | Realtime model |
+|---|---|---|
+| Recall when the agent starts | ✅ | ✅ |
+| Recall before each reply | ✅ | — (no step before a realtime reply; use the tools) |
+| Memory tools (`create_hindsight_tools`) | ✅ | ✅ |
+| Retain the conversation | ✅ | ✅ (needs the model's input audio transcription for the user's side) |
+
+**Session recall** runs once per call. `attach()` starts it, so it overlaps with LiveKit connecting the room and the model, and `HindsightAgent.on_enter` adds the result to the instructions. LiveKit runs `on_enter` in the background, so with a pipeline the first `llm_node` call also waits for the lookup and uses the instructions with memories, even if the user speaks first. A realtime model has no such step: a reply that starts before the lookup finishes (bounded by `recall_timeout`) won't include those memories, which is rare in practice since the lookup starts before the call connects.
+
+**Per-turn recall** runs in [`llm_node`](https://docs.livekit.io/agents/build/nodes/), the step every LLM call in a pipeline goes through. That means:
+
+- It works for spoken turns, chat text input and `session.generate_reply(user_input=...)`. The `on_user_turn_completed` hook only runs for spoken turns.
+- It works with [preemptive generation](https://docs.livekit.io/agents/build/audio/#preemptive-generation): recall starts while LiveKit is still confirming the end of the user's turn, and the preemptive reply is kept. Editing the context in `on_user_turn_completed` would make LiveKit discard it.
+- Memories are only added to a copy of the context for that call, so they never pile up in the session history. When the LLM calls a tool, the follow-up call reuses the same recall result.
+
+As in LiveKit's [RAG example](https://docs.livekit.io/agents/build/external-data/), per-turn memories are added as an `assistant` message just before the user's message, wrapped in `<hindsight_memories>` tags with a note telling the model not to read them out.
+
+**Retain** follows Hindsight's [guidance for conversations](https://hindsight.vectorize.io/developer/api/retain#retaining-a-conversation): each call is one document (`document_id`), written as `Name (timestamp): text` lines, grown with [`update_mode="append"`](https://hindsight.vectorize.io/developer/api/retain#update_mode) so Hindsight only extracts facts from the new part. Lines are sent once both the user and the agent have spoken, sorted by time, because realtime models can deliver the user's transcript after the reply it prompted. Appends are sent one at a time, in order, in the background, so they never delay a reply. `aclose()` sends whatever is left when the call ends.
+
+**Failures never break the call.** If recall fails or takes longer than `recall_timeout`, the agent carries on without memories. If retain fails, the error is logged.
+
+## Memory Tools
+
+`create_hindsight_tools()` gives the model `hindsight_retain`, `hindsight_recall` and `hindsight_reflect` tools, like the other Hindsight framework integrations. They are the way for a realtime model to look things up mid-call, and work with pipelines too:
+
+```python
+from hindsight_livekit import HindsightAgent, create_hindsight_tools
+
+agent = HindsightAgent(
+    memory=memory,
+    llm=inference.RealtimeModel(model="openai/gpt-realtime-mini"),
+    tools=create_hindsight_tools(bank_id=memory.bank_id, client=memory.client, include_reflect=False),
+    instructions=(
+        "You have long-term memory of past calls. When the user asks about themselves, "
+        "their past, or their preferences, call hindsight_recall first. When they share "
+        "something worth remembering, call hindsight_retain."
+    ),
+)
+```
+
+Tell the model when to use the tools, as above: models call them far more reliably with explicit guidance. `hindsight_reflect` runs an LLM on the Hindsight server, so it is the slowest; leave it out for snappier calls. Tool errors are raised as LiveKit `ToolError`, so the model hears what went wrong and can tell the caller.
+
+## Latency
+
+Recall happens while a caller waits, so the defaults are tuned for voice:
+
+- `recall_budget="low"`: Hindsight's [fast lookup](https://hindsight.vectorize.io/developer/api/recall#budget) setting.
+- `recall_max_tokens=1024`: keeps the prompt small.
+- `recall_timeout=3.0`: the longest a reply waits on memory before going ahead without it.
+
+With preemptive generation turned on, most per-turn recall time overlaps with end-of-turn detection.
+
+## Configuration
+
+```python
+HindsightMemory(
+    bank_id="user-123",                  # Required: memory bank to use
+    client=None,                         # Pre-built hindsight_client.Hindsight (optional)
+    hindsight_api_url="...",             # Defaults to HINDSIGHT_API_URL, then Hindsight Cloud
+    api_key="hsk_...",                   # Defaults to HINDSIGHT_API_KEY
+    document_id=None,                    # Defaults to a random "livekit-<uuid>"
+    recall_budget="low",                 # "low", "mid", or "high"
+    recall_max_tokens=1024,              # Max tokens of memories per recall
+    recall_timeout=3.0,                  # Seconds before carrying on without memories
+    recall_types=None,                   # e.g. ["world", "experience"]; None = all
+    tags=None,                           # Tags for retained content
+    recall_tags=None,                    # Tags to filter recall by
+    recall_tags_match="any",             # "any", "all", "any_strict", "all_strict"
+    retain_context="voice conversation", # Source label that guides fact extraction
+    user_name="User",                    # Speaker labels in the stored transcript
+    agent_name="Assistant",
+    enable_session_recall=True,          # Recall known facts when the agent starts
+    session_recall_query="Who is this user? ...",
+    enable_recall=True,                  # Recall before each reply (pipelines)
+    enable_retain=True,                  # Store the conversation
+)
+```
+
+### Global configuration
+
+```python
+from hindsight_livekit import configure
+
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+    recall_budget="low",
+)
+
+memory = HindsightMemory(bank_id="user-123")
+```
+
+### Using your own `Agent` or `llm_node`
+
+`memory.attach(session)` works with any `Agent`. To add recall to an agent that already overrides `llm_node` or `on_enter`, call the memory directly instead of subclassing `HindsightAgent`:
+
+```python
+from livekit.agents import Agent
+
+class MyAgent(Agent):
+    def __init__(self, memory: HindsightMemory) -> None:
+        super().__init__(instructions="...")
+        self.memory = memory
+
+    async def on_enter(self):
+        if memories := await self.memory.recall_session_context():
+            await self.update_instructions(f"{self.instructions}\n\n{memories}")
+
+    async def llm_node(self, chat_ctx, tools, model_settings):
+        chat_ctx = await self.memory.inject_memories(chat_ctx)
+        async for chunk in Agent.default.llm_node(self, chat_ctx, tools, model_settings):
+            yield chunk
+```
+
+## Prerequisites
+
+- `livekit-agents` 1.2 or later
+- A running Hindsight instance, self-hosted or [Hindsight Cloud](https://ui.hindsight.vectorize.io)
+
+## Running Tests
+
+```bash
+uv sync
+uv run pytest tests -v
+```
+
+The unit tests run a real LiveKit `AgentSession` with a scripted LLM and a mocked Hindsight client. The live tests in `tests/test_live_integration.py` run against a real Hindsight server when `HINDSIGHT_API_URL` is set, and also against real pipeline and realtime models through LiveKit Inference when LiveKit Cloud credentials are set:
+
+```bash
+docker run --rm -p 8888:8888 -e HINDSIGHT_API_LLM_PROVIDER=none ghcr.io/vectorize-io/hindsight:latest
+HINDSIGHT_API_URL=http://localhost:8888 uv run pytest tests -v
+
+# optional: real models via LiveKit Inference
+LIVEKIT_URL=wss://... LIVEKIT_API_KEY=... LIVEKIT_API_SECRET=... HINDSIGHT_API_URL=http://localhost:8888 uv run pytest tests -v
+```

hindsight_livekit-0.1.0/examples/realtime_agent.py

@@ -0,0 +1,74 @@
+"""Realtime (speech-to-speech) voice agent with Hindsight memory.
+
+Realtime models answer straight from audio, so there is no step before each reply
+where memories can be added. Instead this agent:
+
+* recalls what is known about the user when the call starts (HindsightAgent adds it
+  to the instructions), and
+* gets ``hindsight_recall`` / ``hindsight_retain`` tools to look things up or save
+  them mid-call.
+
+The conversation is retained as it happens, as with the STT-LLM-TTS example.
+
+Setup is the same as voice_agent.py::
+
+    lk agent console examples/realtime_agent.py
+    lk agent dev examples/realtime_agent.py
+    lk token create --identity me --room hindsight-demo --agent hindsight-realtime-agent --join --open meet
+"""
+
+import logging
+import os
+
+from dotenv import load_dotenv
+from livekit.agents import AgentServer, AgentSession, JobContext, cli, inference
+
+from hindsight_livekit import HindsightAgent, HindsightMemory, create_hindsight_tools
+
+logger = logging.getLogger("agent")
+
+load_dotenv(".env.local")
+
+
+class Assistant(HindsightAgent):
+    def __init__(self, memory: HindsightMemory) -> None:
+        super().__init__(
+            memory=memory,
+            # Any realtime model works: e.g. "google/gemini-live" or "xai/grok-voice".
+            llm=inference.RealtimeModel(model="openai/gpt-realtime-mini"),
+            # The reflect tool runs an LLM on the Hindsight server; leave it out for snappier calls.
+            tools=create_hindsight_tools(bank_id=memory.bank_id, client=memory.client, include_reflect=False),
+            instructions=(
+                "You are a friendly voice assistant with long-term memory of past calls. "
+                "When the user asks about themselves, their past, or their preferences, call "
+                "hindsight_recall first. When they share something worth remembering, call "
+                "hindsight_retain. Keep replies to one to three short sentences."
+            ),
+        )
+
+    async def on_enter(self) -> None:
+        # Recall what's known about the user first, so the greeting can use it.
+        await super().on_enter()
+        self.session.generate_reply(instructions="Greet the user briefly, by name if you know it.")
+
+
+server = AgentServer()
+
+
+@server.rtc_session(agent_name="hindsight-realtime-agent")
+async def entrypoint(ctx: JobContext) -> None:
+    bank_id = os.environ.get("HINDSIGHT_BANK_ID", "livekit-demo-user")
+    logger.info(f"using Hindsight bank {bank_id}")
+
+    session = AgentSession()
+
+    memory = HindsightMemory(bank_id=bank_id, document_id=ctx.room.name)
+    memory.attach(session)
+    ctx.add_shutdown_callback(memory.aclose)
+
+    await session.start(agent=Assistant(memory), room=ctx.room)
+    await ctx.connect()
+
+
+if __name__ == "__main__":
+    cli.run_app(server)