recall-livekit 0.1.0__py3-none-any.whl

recall_livekit/__init__.py

@@ -0,0 +1,41 @@
+"""Recall by Polign for LiveKit Agents.
+
+One ``RecallMemory`` per worker process owns the Recall subprocess. Each
+caller gets a ``SubjectMemory`` view on it, and ``RecallAgent`` (or ``attach``
+for an existing Agent subclass) loads that caller's facts before the first
+reply and exposes a ``remember`` tool so the model can store new ones.
+"""
+
+from importlib import resources
+
+from .agent import RecallAgent
+from .hooks import MemoryBinding, attach
+from .memory import PredicateSpec, RecallMemory, SubjectMemory
+from .render import DEFAULT_TEMPLATE, compose_instructions, render_beliefs
+from .tools import build_forget_tool, build_remember_tool
+
+__all__ = [
+    "DEFAULT_TEMPLATE",
+    "MemoryBinding",
+    "PredicateSpec",
+    "RecallAgent",
+    "RecallMemory",
+    "SubjectMemory",
+    "VOICE_REGISTRY",
+    "attach",
+    "build_forget_tool",
+    "build_remember_tool",
+    "compose_instructions",
+    "render_beliefs",
+]
+
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("recall-livekit")
+except Exception:  # pragma: no cover - source checkout without metadata
+    __version__ = "0.1.0"
+
+#: Path of the starter predicate registry for phone and voice callers. Pass it
+#: as ``predicates=`` to :meth:`RecallMemory.open` or set ``POLIGN_PREDICATES``.
+VOICE_REGISTRY = str(resources.files(__name__).joinpath("registry_voice.json"))

recall_livekit/agent.py

@@ -0,0 +1,101 @@
+"""An Agent that remembers the caller."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from livekit.agents import llm
+from livekit.agents.voice import Agent
+
+from .hooks import MemoryBinding
+from .memory import SubjectMemory
+from .render import DEFAULT_TEMPLATE
+from .tools import build_forget_tool, build_remember_tool
+
+
+class RecallAgent(Agent):
+    """A LiveKit Agent whose instructions carry the caller's remembered facts.
+
+    On ``on_enter`` it loads every current belief for the subject and appends
+    them to the instructions, before the first reply. The ``remember`` tool
+    writes new facts and reloads the block. When a caller has more beliefs
+    than ``memory.limit``, each user turn also runs a search and adds the
+    matching facts to that turn.
+
+    Subclasses that override ``on_enter`` must ``await super().on_enter()``
+    first, before generating a greeting. LiveKit runs ``on_enter`` as a task
+    after ``session.start`` returns; ``wait_for_memory`` awaits its first load.
+    """
+
+    def __init__(
+        self,
+        *,
+        memory: SubjectMemory,
+        instructions: str,
+        context_template: str = DEFAULT_TEMPLATE,
+        who: str = "the caller",
+        remember_tool: bool = True,
+        forget_tool: bool = False,
+        search_when_overflowed: bool = True,
+        tools: list[llm.Tool | llm.Toolset] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if not isinstance(instructions, str):
+            raise TypeError("RecallAgent needs plain string instructions")
+        self._binding = MemoryBinding(
+            self,
+            memory,
+            base_instructions=instructions,
+            context_template=context_template,
+            who=who,
+            remember_tool=remember_tool,
+        )
+        self._search_when_overflowed = search_when_overflowed
+        self._memory_loaded = asyncio.Event()
+        all_tools: list[llm.Tool | llm.Toolset] = list(tools or [])
+        if remember_tool:
+            all_tools.append(build_remember_tool(memory, on_change=self.refresh_memory))
+        if forget_tool:
+            all_tools.append(build_forget_tool(memory, on_change=self.refresh_memory))
+        super().__init__(instructions=instructions, tools=all_tools, **kwargs)
+
+    @property
+    def memory(self) -> SubjectMemory:
+        return self._binding.memory
+
+    @property
+    def base_instructions(self) -> str:
+        """The instructions without the memory block."""
+        return self._binding.base_instructions
+
+    async def refresh_memory(self) -> None:
+        """Reload the caller's beliefs and rewrite the instructions."""
+        await self._binding.refresh()
+
+    async def on_enter(self) -> None:
+        try:
+            await self.refresh_memory()
+        finally:
+            self._memory_loaded.set()
+
+    async def wait_for_memory(self) -> None:
+        """Wait until ``on_enter`` has loaded the caller's beliefs. LiveKit runs
+        ``on_enter`` as a task after ``session.start`` returns, so tests and
+        code that inspects the instructions right after start should await this."""
+        await self._memory_loaded.wait()
+
+    async def on_user_turn_completed(
+        self, turn_ctx: llm.ChatContext, new_message: llm.ChatMessage
+    ) -> None:
+        if not self._search_when_overflowed or not self.memory.overflowed:
+            return
+        text = new_message.text_content
+        if not text:
+            return
+        hits = await self.memory.search(text)
+        # Facts already in the instructions add nothing to the turn.
+        shown = {(b.predicate, str(b.value)) for b in self.memory.beliefs}
+        extra = [b for b in hits if (b.predicate, str(b.value)) not in shown]
+        if extra:
+            turn_ctx.add_message(role="system", content=self._binding.turn_context(extra))

recall_livekit/hooks.py

@@ -0,0 +1,91 @@
+"""Attach Recall memory to an Agent subclass you already have."""
+
+from __future__ import annotations
+
+from livekit.agents import llm
+from livekit.agents.voice import Agent
+
+from .memory import SubjectMemory
+from .render import DEFAULT_TEMPLATE, compose_instructions, render_beliefs
+from .tools import build_forget_tool, build_remember_tool
+
+
+class MemoryBinding:
+    """Keeps an agent's instructions in step with one caller's beliefs."""
+
+    def __init__(
+        self,
+        agent: Agent,
+        memory: SubjectMemory,
+        *,
+        base_instructions: str,
+        context_template: str = DEFAULT_TEMPLATE,
+        who: str = "the caller",
+        remember_tool: bool = True,
+    ) -> None:
+        self.agent = agent
+        self.memory = memory
+        self.base_instructions = base_instructions
+        self.context_template = context_template
+        self.who = who
+        self.remember_tool = remember_tool
+
+    def render(self) -> str:
+        return render_beliefs(
+            self.memory.beliefs,
+            registry=self.memory.registry,
+            template=self.context_template,
+            who=self.who,
+            remember_tool=self.remember_tool,
+        )
+
+    async def refresh(self) -> None:
+        """Reload the caller's beliefs and rewrite the agent's instructions."""
+        await self.memory.load()
+        await self.agent.update_instructions(compose_instructions(self.base_instructions, self.render()))
+
+    def turn_context(self, hits: list) -> str:
+        """The block added to a turn when a per-turn search found more facts."""
+        return render_beliefs(
+            hits,
+            registry=self.memory.registry,
+            template=self.context_template,
+            who=self.who,
+            remember_tool=False,
+        )
+
+
+async def attach(
+    agent: Agent,
+    memory: SubjectMemory,
+    *,
+    context_template: str = DEFAULT_TEMPLATE,
+    who: str = "the caller",
+    remember_tool: bool = True,
+    forget_tool: bool = False,
+) -> MemoryBinding:
+    """Give an existing Agent the memory block and the ``remember`` tool.
+
+    Await it before ``session.start`` or at the top of the agent's ``on_enter``.
+    The agent's instructions must be a plain string. Per-turn search for
+    callers with more beliefs than fit the block needs ``RecallAgent``.
+    """
+    instructions = agent.instructions
+    if not isinstance(instructions, str):
+        raise TypeError("attach needs plain string instructions; Instructions objects are not supported")
+    binding = MemoryBinding(
+        agent,
+        memory,
+        base_instructions=instructions,
+        context_template=context_template,
+        who=who,
+        remember_tool=remember_tool,
+    )
+    tools: list[llm.Tool | llm.Toolset] = list(agent.tools)
+    if remember_tool:
+        tools.append(build_remember_tool(memory, on_change=binding.refresh))
+    if forget_tool:
+        tools.append(build_forget_tool(memory, on_change=binding.refresh))
+    await agent.update_tools(tools)
+    await binding.refresh()
+    return binding

recall_livekit/memory.py

@@ -0,0 +1,248 @@
+"""The shared Recall client and the per-caller view built on it."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from polign_recall import Belief, Client, RecallError, RememberResult
+
+logger = logging.getLogger("recall_livekit")
+
+T = TypeVar("T")
+
+_MISSING: Any = object()
+
+
+def _describe(exc: BaseException) -> str:
+    text = str(exc)
+    return f"{type(exc).__name__}: {text}" if text else type(exc).__name__
+
+
+@dataclass(frozen=True)
+class PredicateSpec:
+    """One entry of the Recall predicate registry."""
+
+    name: str
+    cardinality: str  # "single" or "multi"
+    value_type: str  # "string", "number", or "boolean"
+    description: str
+
+
+class RecallMemory:
+    """One Recall client for a worker process.
+
+    Create it once in the server's ``setup_fnc`` (LiveKit calls that once per
+    process) and keep it in ``JobProcess.userdata``. Every ``polign_recall.Client``
+    is a ``polign mcp`` subprocess, so one per turn or per session is wasteful.
+    Calls are serialized on that subprocess; the local read path is a few
+    milliseconds, so a handful of concurrent sessions per process share it well.
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+        self._registry: dict[str, PredicateSpec] = {}
+        for entry in client.predicates():
+            spec = PredicateSpec(
+                name=entry["predicate"],
+                cardinality=entry.get("cardinality", "single"),
+                value_type=entry.get("value_type") or "string",
+                description=entry.get("description", ""),
+            )
+            self._registry[spec.name] = spec
+
+    @classmethod
+    def open(
+        cls,
+        *,
+        url: str | None = None,
+        api_key: str | None = None,
+        collection: str | None = None,
+        predicates: str | None = None,
+        command: Sequence[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        timeout: float = 30.0,
+        write: bool = True,
+    ) -> RecallMemory:
+        """Start the Recall subprocess and read its predicate registry.
+
+        ``url``, ``api_key``, ``collection`` and ``predicates`` (a registry file
+        path) become the ``POLIGN_URL``, ``POLIGN_API_KEY``, ``POLIGN_COLLECTION``
+        and ``POLIGN_PREDICATES`` variables of the subprocess; anything left
+        unset falls through to the worker's environment. ``command`` replaces
+        the default ``polign mcp -memory-only -write`` argv, for a binary that
+        is not on ``PATH``.
+        """
+        merged = dict(env or {})
+        for key, value in (
+            ("POLIGN_URL", url),
+            ("POLIGN_API_KEY", api_key),
+            ("POLIGN_COLLECTION", collection),
+            ("POLIGN_PREDICATES", predicates),
+        ):
+            if value is not None:
+                merged[key] = value
+        client = Client(command=command, env=merged, timeout=timeout, write=write)
+        try:
+            return cls(client)
+        except BaseException:
+            client.close()
+            raise
+
+    @property
+    def client(self) -> Client:
+        return self._client
+
+    @property
+    def registry(self) -> Mapping[str, PredicateSpec]:
+        """The closed set of predicates this Recall instance accepts."""
+        return self._registry
+
+    def for_subject(
+        self,
+        subject: str,
+        *,
+        limit: int = 20,
+        read_timeout: float = 0.5,
+        write_timeout: float = 5.0,
+    ) -> SubjectMemory:
+        """A view of one caller's memory. ``subject`` should be a stable, auth-derived
+        identifier such as the participant identity, never the room name."""
+        if not subject or not subject.strip():
+            raise ValueError("subject must be a non-empty string")
+        return SubjectMemory(
+            self, subject, limit=limit, read_timeout=read_timeout, write_timeout=write_timeout
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> RecallMemory:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class SubjectMemory:
+    """One caller's beliefs, with the async helpers the agent hooks need.
+
+    Reads fail open: a slow or unavailable Recall returns the last loaded
+    beliefs (or none) and logs a warning, so the voice session keeps going.
+    Writes raise, so the tool can tell the model the fact was not saved.
+    """
+
+    def __init__(
+        self,
+        memory: RecallMemory,
+        subject: str,
+        *,
+        limit: int,
+        read_timeout: float,
+        write_timeout: float,
+    ) -> None:
+        if limit < 1:
+            raise ValueError("limit must be at least 1")
+        self._memory = memory
+        self.subject = subject
+        self.limit = limit
+        self.read_timeout = read_timeout
+        self.write_timeout = write_timeout
+        self.beliefs: list[Belief] = []
+        self.loaded = False
+
+    @property
+    def registry(self) -> Mapping[str, PredicateSpec]:
+        return self._memory.registry
+
+    @property
+    def overflowed(self) -> bool:
+        """True when the last load hit the cap, so beliefs may be missing from
+        the prompt and a per-turn search is worth running."""
+        return len(self.beliefs) >= self.limit
+
+    async def load(self) -> list[Belief]:
+        """Every current belief about the subject, up to ``limit``."""
+        client = self._memory.client
+        try:
+            beliefs = await self._call(
+                lambda: client.recall(subject=self.subject, limit=self.limit), self.read_timeout
+            )
+        except (RecallError, asyncio.TimeoutError) as exc:
+            logger.warning("recall load failed for subject %r: %s", self.subject, _describe(exc))
+            return self.beliefs
+        self.beliefs = list(beliefs)
+        self.loaded = True
+        return self.beliefs
+
+    async def search(self, query: str, *, k: int = 5) -> list[Belief]:
+        """Beliefs about the subject that match ``query``. Uses the embedder the
+        Recall subprocess was started with; the default is word overlap."""
+        client = self._memory.client
+        try:
+            hits = await self._call(
+                lambda: client.recall(subject=self.subject, query=query, limit=k),
+                self.read_timeout,
+            )
+        except (RecallError, asyncio.TimeoutError) as exc:
+            logger.warning("recall search failed for subject %r: %s", self.subject, _describe(exc))
+            return []
+        return list(hits)
+
+    async def remember(self, predicate: str, value: Any, *, source: str | None = None) -> RememberResult:
+        client = self._memory.client
+        result = await self._call(
+            lambda: client.remember(self.subject, predicate, value, source=source),
+            self.write_timeout,
+        )
+        if not isinstance(result, RememberResult):  # pragma: no cover - typed path only
+            raise RecallError("unexpected extraction result from a typed remember")
+        return result
+
+    async def forget(self, predicate: str, value: Any = _MISSING, *, all: bool = False) -> int:
+        client = self._memory.client
+        if value is _MISSING:
+            return await self._call(
+                lambda: client.forget(self.subject, predicate, all=all), self.write_timeout
+            )
+        return await self._call(
+            lambda: client.forget(self.subject, predicate, value), self.write_timeout
+        )
+
+    def coerce(self, predicate: str, value: Any) -> Any:
+        """Turn a model-supplied value into the registry's type for ``predicate``."""
+        spec = self.registry.get(predicate)
+        if spec is None:
+            raise ValueError(f"unknown memory type {predicate!r}")
+        if spec.value_type == "number":
+            if isinstance(value, bool):
+                raise ValueError(f"{predicate} takes a number")
+            if isinstance(value, (int, float)):
+                return value
+            text = str(value).strip().replace(",", "")
+            try:
+                number = float(text)
+            except ValueError as exc:
+                raise ValueError(f"{predicate} takes a number, got {value!r}") from exc
+            return int(number) if number.is_integer() else number
+        if spec.value_type == "boolean":
+            if isinstance(value, bool):
+                return value
+            text = str(value).strip().lower()
+            if text in ("true", "yes", "y", "1", "on"):
+                return True
+            if text in ("false", "no", "n", "0", "off"):
+                return False
+            raise ValueError(f"{predicate} takes yes or no, got {value!r}")
+        text = str(value).strip()
+        if not text:
+            raise ValueError(f"{predicate} needs a value")
+        return text
+
+    async def _call(self, fn: Callable[[], T], timeout: float) -> T:
+        # The Recall client is blocking; a thread keeps the audio pipeline
+        # responsive. On timeout the thread finishes on its own later.
+        return await asyncio.wait_for(asyncio.to_thread(fn), timeout)

recall_livekit/registry_voice.json

@@ -0,0 +1,57 @@
+{
+  "name": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "The name the caller asks to be called"
+  },
+  "preferred_language": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "The language the caller wants to speak"
+  },
+  "callback_number": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "The phone number the caller wants to be called back on"
+  },
+  "email": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "The email address the caller wants written follow-ups sent to"
+  },
+  "timezone": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "The caller's timezone or city, for scheduling"
+  },
+  "account_tier": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "The plan or membership level the caller is on"
+  },
+  "consents_to_recording": {
+    "cardinality": "single",
+    "value_type": "boolean",
+    "description": "Whether the caller agreed to have calls recorded"
+  },
+  "prefers_response_style": {
+    "cardinality": "single",
+    "value_type": "string",
+    "description": "How the caller likes answers, such as brief or step by step"
+  },
+  "open_issue": {
+    "cardinality": "multi",
+    "value_type": "string",
+    "description": "A problem the caller reported that is not resolved yet"
+  },
+  "owns_product": {
+    "cardinality": "multi",
+    "value_type": "string",
+    "description": "A product or service the caller owns or subscribes to"
+  },
+  "uses_technology": {
+    "cardinality": "multi",
+    "value_type": "string",
+    "description": "A device, platform, or tool the caller uses"
+  }
+}

recall_livekit/render.py

@@ -0,0 +1,74 @@
+"""Turn beliefs into the block of text the model reads."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from polign_recall import Belief
+
+from .memory import PredicateSpec
+
+DEFAULT_TEMPLATE = "<recall_memory>\n{context}\n</recall_memory>"
+
+
+def _observed(belief: Belief) -> str:
+    observed = getattr(belief, "observed_at", "") or ""
+    return observed[:10]
+
+
+def render_beliefs(
+    beliefs: Iterable[Belief],
+    *,
+    registry: Mapping[str, PredicateSpec] | None = None,
+    template: str = DEFAULT_TEMPLATE,
+    who: str = "the caller",
+    remember_tool: bool = True,
+) -> str:
+    """Render current beliefs as a memory block.
+
+    Single-valued predicates print one line each; multi-valued ones are
+    grouped on one line. ``template`` must contain a literal ``{context}``.
+    """
+    if "{context}" not in template:
+        raise ValueError("context template must contain a literal {context} placeholder")
+
+    grouped: dict[str, list[Belief]] = {}
+    for belief in beliefs:
+        grouped.setdefault(belief.predicate, []).append(belief)
+
+    lines: list[str] = []
+    if grouped:
+        lines.append(
+            f"Facts remembered about {who} from earlier conversations. "
+            f"Treat them as true unless {who} says otherwise, and use them naturally "
+            "without reading the list aloud."
+        )
+        for predicate, items in grouped.items():
+            spec = registry.get(predicate) if registry else None
+            multi = spec is not None and spec.cardinality == "multi"
+            if multi or len(items) > 1:
+                values = "; ".join(str(b.value) for b in items)
+                lines.append(f"- {predicate}: {values}")
+            else:
+                belief = items[0]
+                when = _observed(belief)
+                suffix = f" (observed {when})" if when else ""
+                lines.append(f"- {predicate}: {belief.value}{suffix}")
+    else:
+        lines.append(f"Nothing is remembered about {who} yet.")
+
+    if remember_tool:
+        kinds = ", ".join(registry.keys()) if registry else "the registered memory types"
+        lines.append(
+            f"When {who} states a lasting fact of one of these kinds, call the remember tool "
+            f"with it: {kinds}. Corrections go through the same tool. "
+            "Do not mention the memory system unless asked."
+        )
+
+    return template.replace("{context}", "\n".join(lines))
+
+
+def compose_instructions(base: str, memory_block: str) -> str:
+    """The agent's instructions with the memory block appended."""
+    base = base.rstrip()
+    return f"{base}\n\n{memory_block}" if base else memory_block

recall_livekit/tools.py

@@ -0,0 +1,139 @@
+"""Function tools that let the voice model write memory."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from livekit.agents import llm
+from polign_recall import RecallError
+
+from .memory import SubjectMemory
+
+OnChange = Callable[[], Awaitable[None]] | None
+
+
+def _predicate_property(memory: SubjectMemory) -> dict[str, Any]:
+    names = list(memory.registry)
+    described = "; ".join(
+        f"{spec.name}: {spec.description or spec.name}"
+        + (" (can hold several values)" if spec.cardinality == "multi" else "")
+        for spec in memory.registry.values()
+    )
+    return {
+        "type": "string",
+        "enum": names,
+        "description": f"The kind of fact. One of: {described}.",
+    }
+
+
+def build_remember_tool(memory: SubjectMemory, *, on_change: OnChange = None) -> llm.RawFunctionTool:
+    """A ``remember`` tool whose predicate list is the Recall registry.
+
+    ``on_change`` runs after a successful write, so the agent can reload its
+    memory block before the next turn.
+    """
+    schema = {
+        "name": "remember",
+        "description": (
+            "Save a lasting fact the caller stated about themselves, such as their name, "
+            "a preference, or an open issue. Call it once per fact, as soon as the fact is "
+            "clear. Storing a new value for a single-valued kind replaces the old one."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "predicate": _predicate_property(memory),
+                "value": {
+                    "type": "string",
+                    "description": "The fact itself, short and in the caller's words. "
+                    "Numbers as digits, yes/no facts as true or false.",
+                },
+            },
+            "required": ["predicate", "value"],
+            "additionalProperties": False,
+        },
+    }
+
+    async def remember(raw_arguments: dict[str, object]) -> str:
+        predicate = str(raw_arguments.get("predicate", "")).strip()
+        if predicate not in memory.registry:
+            raise llm.ToolError(
+                f"Unknown memory kind {predicate!r}. Use one of: {', '.join(memory.registry)}."
+            )
+        try:
+            value = memory.coerce(predicate, raw_arguments.get("value"))
+        except ValueError as exc:
+            raise llm.ToolError(str(exc)) from exc
+        try:
+            result = await memory.remember(predicate, value)
+        except RecallError as exc:
+            raise llm.ToolError(f"The fact was not saved: {exc}") from exc
+        except asyncio.TimeoutError as exc:
+            raise llm.ToolError("Memory is slow right now; the fact was not saved.") from exc
+        if on_change is not None:
+            await on_change()
+        if result.already_known:
+            return f"Already remembered: {predicate} is {value}."
+        if result.superseded:
+            old = ", ".join(str(b.value) for b in result.superseded)
+            return f"Updated {predicate} to {value}; it was {old}."
+        return f"Remembered {predicate}: {value}."
+
+    return llm.function_tool(remember, raw_schema=schema)
+
+
+def build_forget_tool(memory: SubjectMemory, *, on_change: OnChange = None) -> llm.RawFunctionTool:
+    """A ``forget`` tool. Off by default in ``RecallAgent``; enable it when the
+    caller should be able to withdraw a fact by asking."""
+    schema = {
+        "name": "forget",
+        "description": (
+            "Withdraw a remembered fact when the caller asks you to forget it. "
+            "Give the exact value to withdraw, or set everything to true to withdraw every "
+            "value of that kind. The record of the change is kept."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "predicate": _predicate_property(memory),
+                "value": {"type": "string", "description": "The value to withdraw."},
+                "everything": {
+                    "type": "boolean",
+                    "description": "Withdraw every value of this kind instead of one.",
+                },
+            },
+            "required": ["predicate"],
+            "additionalProperties": False,
+        },
+    }
+
+    async def forget(raw_arguments: dict[str, object]) -> str:
+        predicate = str(raw_arguments.get("predicate", "")).strip()
+        if predicate not in memory.registry:
+            raise llm.ToolError(
+                f"Unknown memory kind {predicate!r}. Use one of: {', '.join(memory.registry)}."
+            )
+        everything = bool(raw_arguments.get("everything", False))
+        raw_value = raw_arguments.get("value")
+        if not everything and (raw_value is None or str(raw_value).strip() == ""):
+            raise llm.ToolError("Give the value to withdraw, or set everything to true.")
+        try:
+            if everything:
+                count = await memory.forget(predicate, all=True)
+            else:
+                count = await memory.forget(predicate, memory.coerce(predicate, raw_value))
+        except ValueError as exc:
+            raise llm.ToolError(str(exc)) from exc
+        except RecallError as exc:
+            raise llm.ToolError(f"Nothing was withdrawn: {exc}") from exc
+        except asyncio.TimeoutError as exc:
+            raise llm.ToolError("Memory is slow right now; nothing was withdrawn.") from exc
+        if on_change is not None:
+            await on_change()
+        if count == 0:
+            return f"There was no remembered {predicate} to withdraw."
+        return f"Withdrew {count} remembered value(s) of {predicate}."
+
+    return llm.function_tool(forget, raw_schema=schema)

recall_livekit-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: recall-livekit
+Version: 0.1.0
+Summary: Typed, correctable long-term memory for LiveKit voice agents, backed by Recall by Polign
+Project-URL: Homepage, https://polign.com
+Project-URL: Documentation, https://polign.com/integrations.html
+Project-URL: Repository, https://github.com/Polign/polign
+Project-URL: Issues, https://github.com/Polign/polign/issues
+Author: Polign
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent memory,livekit,polign,recall,voice agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: livekit-agents<2,>=1.8
+Requires-Dist: polign-recall>=0.2.0
+Description-Content-Type: text/markdown
+
+# recall-livekit
+
+Long-term memory for [LiveKit Agents](https://github.com/livekit/agents) voice
+agents, backed by [Recall by Polign](https://polign.com/recall.html).
+
+The agent loads everything it knows about the caller before the first reply,
+and the model saves new facts through a `remember` tool. Facts are typed:
+each one is a predicate from a closed registry with a value, so "call me Sam"
+replaces the old name instead of piling up a second one, and the history of
+the change is kept. No second model runs on the read path, and no embedding
+service is needed.
+
+```bash
+pip install recall-livekit "livekit-agents[openai,deepgram,cartesia,silero]"
+```
+
+Recall runs as a `polign mcp` subprocess, so the `polign` CLI has to be on the
+worker's `PATH` (or passed as `command=`), and it needs a polign_db server to
+store into. [Get started](https://polign.com/developers.html) covers both.
+
+## Usage
+
+```python
+from livekit.agents import AgentServer, AgentSession, JobContext, JobProcess, cli
+from livekit.plugins import cartesia, deepgram, openai, silero
+from recall_livekit import VOICE_REGISTRY, RecallAgent, RecallMemory
+
+server = AgentServer()
+
+
+def setup(proc: JobProcess) -> None:
+    # one Recall subprocess per worker process
+    proc.userdata["recall"] = RecallMemory.open(
+        url="http://memory.internal:23000",   # or POLIGN_URL in the environment
+        predicates=VOICE_REGISTRY,            # or your own registry file
+    )
+
+
+server.setup_fnc = setup
+
+
+@server.rtc_session()
+async def entrypoint(ctx: JobContext) -> None:
+    participant = await ctx.wait_for_participant()
+    memory = ctx.proc.userdata["recall"].for_subject(participant.identity)
+
+    session = AgentSession(
+        stt=deepgram.STT(), llm=openai.LLM(model="gpt-4.1-mini"),
+        tts=cartesia.TTS(), vad=silero.VAD.load(),
+    )
+    await session.start(
+        agent=RecallAgent(
+            memory=memory,
+            instructions="You are the support line for Acme. Use what you remember about the caller.",
+        ),
+        room=ctx.room,
+    )
+
+
+if __name__ == "__main__":
+    cli.run_app(server)
+```
+
+What happens on a call:
+
+1. `on_enter` loads the caller's current beliefs and appends them to the
+   instructions inside a `<recall_memory>` block, before the greeting.
+2. The caller says "actually call me Sam, and I moved to Denver". The model
+   calls `remember` twice. Recall supersedes the old name and timezone, and
+   the agent rewrites its instructions so the next sentence already uses Sam.
+3. A week later the same identity calls back and step 1 finds the facts.
+
+Nothing is searched per turn. A caller's typed facts are a short list, so the
+whole set fits in the prompt. When a caller has more beliefs than `limit`
+(default 20), each user turn also runs a search and adds matching facts to
+that turn only.
+
+## Your own Agent subclass
+
+```python
+from recall_livekit import attach
+
+agent = FrontDesk()                      # any Agent with string instructions
+await attach(agent, memory, who="the guest")
+await session.start(agent, room=ctx.room)
+```
+
+`attach` adds the memory block and the `remember` tool. It does not do the
+per-turn search for overflowing callers; use `RecallAgent` for that.
+
+## Options
+
+| Where | Option | Default | What it does |
+|---|---|---|---|
+| `RecallMemory.open` | `url`, `api_key`, `collection`, `predicates` | worker environment | Connection for the subprocess (`POLIGN_URL`, `POLIGN_API_KEY`, `POLIGN_COLLECTION`, `POLIGN_PREDICATES`) |
+| `RecallMemory.open` | `command` | `polign mcp -memory-only -write` | The subprocess argv, for a binary that is not on `PATH` |
+| `for_subject` | `limit` | 20 | Beliefs loaded into the prompt; above it, per-turn search kicks in |
+| `for_subject` | `read_timeout`, `write_timeout` | 0.5 s, 5 s | Reads fail open (last known beliefs); writes tell the model the fact was not saved |
+| `RecallAgent` | `context_template` | `<recall_memory>\n{context}\n</recall_memory>` | Wrapper around the block; must contain `{context}` |
+| `RecallAgent` | `who` | `"the caller"` | How the block refers to the person |
+| `RecallAgent` | `remember_tool`, `forget_tool` | on, off | Which tools the model gets |
+| `RecallAgent` | `search_when_overflowed` | on | Per-turn search when the caller has more beliefs than `limit` |
+
+## Custom predicates
+
+Predicates are a JSON file. The `remember` tool's schema is built from it, so
+the model only ever sees the names you allow.
+
+```json
+{
+  "name":       { "cardinality": "single", "value_type": "string",  "description": "The name the caller asks to be called" },
+  "open_issue": { "cardinality": "multi",  "value_type": "string",  "description": "A problem the caller reported that is not resolved yet" }
+}
+```
+
+`single` means a newer value replaces the old one; `multi` means each value
+is an additional fact. `value_type` is `string`, `number`, or `boolean`. The
+file replaces Recall's built-in registry entirely. `VOICE_REGISTRY` is a
+starter set for callers: name, preferred language, callback number, email,
+timezone, account tier, recording consent, response style, open issues,
+owned products, and technologies used.
+
+## Subjects and retention
+
+Use a stable, auth-derived identifier as the subject, such as the participant
+identity your token server issued. Never the room name. Recall keeps the
+record of every change while the current view updates; enable `forget_tool`
+if callers should be able to withdraw a fact by asking, and see the Recall
+docs for retention and export.
+
+## Development
+
+`polign-recall` is not on PyPI yet, so install it from source first:
+
+```bash
+python -m pip install "polign-recall @ git+https://github.com/Polign/recall@python-v0.2.0#subdirectory=python"
+cd python/recall-livekit
+python -m pip install -e . pytest pytest-asyncio
+pytest tests/unit_tests -q                # fake Recall subprocess, scripted model
+pytest tests/integration_tests -v         # real polign-server and polign CLI
+```
+
+The integration tests locate the binaries like the SDK's tests do
+(`POLIGN_SERVER`, `POLIGN_SOURCE`, `POLIGN_SERVER_VERSION`, or the latest
+release download) and skip when none is found.

recall_livekit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+recall_livekit/__init__.py,sha256=C7xszlpLhHBqM6QHskx0VaB9lIy7mZndC86CcyEYVk0,1371
+recall_livekit/agent.py,sha256=kJYLelOVYpneM6eVxAJ0aYM4KJkaRYe7plDf5NpT4DQ,3832
+recall_livekit/hooks.py,sha256=t0MpDriHo9MKhvFtFn1-seCrXpAO_zn1kPVlTRXUKc8,3043
+recall_livekit/memory.py,sha256=NoOLpfia_Vg7jyNXVZjGdFlH2J-7sjkLwDwdBzIbW0s,9195
+recall_livekit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+recall_livekit/registry_voice.json,sha256=MlzMq5mL8cls4l1FVnMw2hr9BkD2CAZucc0MlA2kaR0,1692
+recall_livekit/render.py,sha256=iosFDXy0wgbfFdr5PtugjFBSu0B-E47bld6OPyYfTEo,2672
+recall_livekit/tools.py,sha256=sV87Fy_JEh8jKCwcTr2cQZg_1ZrIktTPijsMVLR-y_k,5718
+recall_livekit-0.1.0.dist-info/METADATA,sha256=ZQIMlO0BIRJJEPt-nM3x-5PIqZEvs-RCgBYnanTAD1k,7098
+recall_livekit-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+recall_livekit-0.1.0.dist-info/licenses/LICENSE,sha256=ra9FdQ2xyykGuwkTiZDGe8MaUdF61EbNfS6xW16vQUY,11343
+recall_livekit-0.1.0.dist-info/RECORD,,

recall_livekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

recall_livekit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Polign, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.