hindsight-langgraph 0.1.1__py3-none-any.whl

hindsight_langgraph/__init__.py

@@ -0,0 +1,93 @@
+"""Hindsight-LangGraph: Persistent memory for LangGraph and LangChain agents.
+
+Provides Hindsight-backed tools, nodes, and a BaseStore adapter,
+giving agents long-term memory across conversations.
+
+The **tools** pattern works with both LangChain and LangGraph — only
+``langchain-core`` is required. The **nodes** and **store** patterns
+require ``langgraph`` (install with ``pip install hindsight-langgraph[langgraph]``).
+
+Basic usage with tools (LangChain or LangGraph)::
+
+    from hindsight_client import Hindsight
+    from hindsight_langgraph import create_hindsight_tools
+
+    client = Hindsight(base_url="http://localhost:8888")
+    tools = create_hindsight_tools(client=client, bank_id="user-123")
+
+    # Bind tools to your model
+    model = ChatOpenAI(model="gpt-4o").bind_tools(tools)
+
+Usage with memory nodes (requires langgraph)::
+
+    from hindsight_langgraph import create_recall_node, create_retain_node
+
+    recall = create_recall_node(client=client, bank_id="user-123")
+    retain = create_retain_node(client=client, bank_id="user-123")
+
+    builder.add_node("recall", recall)
+    builder.add_node("agent", agent_node)
+    builder.add_node("retain", retain)
+    builder.add_edge("recall", "agent")
+    builder.add_edge("agent", "retain")
+
+Usage with BaseStore (requires langgraph)::
+
+    from hindsight_langgraph import HindsightStore
+
+    store = HindsightStore(client=client)
+    graph = builder.compile(checkpointer=checkpointer, store=store)
+"""
+
+from .config import (
+    HindsightLangGraphConfig,
+    configure,
+    get_config,
+    reset_config,
+)
+from .errors import HindsightError
+from .tools import create_hindsight_tools
+
+
+def __getattr__(name: str):
+    """Lazy-import LangGraph-specific modules so langgraph is optional."""
+    if name == "create_recall_node" or name == "create_retain_node":
+        try:
+            from .nodes import create_recall_node, create_retain_node
+        except ImportError:
+            raise ImportError(
+                f"'{name}' requires langgraph. Install with: pip install hindsight-langgraph[langgraph]"
+            ) from None
+        return (
+            create_recall_node if name == "create_recall_node" else create_retain_node
+        )
+
+    if name == "HindsightStore":
+        try:
+            from .store import HindsightStore
+        except ImportError:
+            raise ImportError(
+                "HindsightStore requires langgraph. Install with: pip install hindsight-langgraph[langgraph]"
+            ) from None
+        return HindsightStore
+
+    raise AttributeError(f"module 'hindsight_langgraph' has no attribute {name!r}")
+
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "configure",
+    "get_config",
+    "reset_config",
+    "HindsightLangGraphConfig",
+    "HindsightError",
+    "create_hindsight_tools",
+]
+
+try:
+    import langgraph  # noqa: F401
+
+    __all__ += ["create_recall_node", "create_retain_node", "HindsightStore"]
+except ImportError:
+    pass

hindsight_langgraph/_client.py

@@ -0,0 +1,32 @@
+"""Shared Hindsight client resolution logic."""
+
+from typing import Any, Optional
+
+from hindsight_client import Hindsight
+
+from .config import get_config
+from .errors import HindsightError
+
+
+def resolve_client(
+    client: Optional[Hindsight],
+    hindsight_api_url: Optional[str],
+    api_key: Optional[str],
+) -> Hindsight:
+    """Resolve a Hindsight client from explicit args or global config."""
+    if client is not None:
+        return client
+
+    config = get_config()
+    url = hindsight_api_url or (config.hindsight_api_url if config else None)
+    key = api_key or (config.api_key if config else None)
+
+    if url is None:
+        raise HindsightError(
+            "No Hindsight API URL configured. Pass client= or hindsight_api_url=, or call configure() first."
+        )
+
+    kwargs: dict[str, Any] = {"base_url": url, "timeout": 30.0}
+    if key:
+        kwargs["api_key"] = key
+    return Hindsight(**kwargs)

hindsight_langgraph/config.py

@@ -0,0 +1,91 @@
+"""Global configuration for Hindsight-LangGraph integration."""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_HINDSIGHT_API_URL = "https://api.hindsight.vectorize.io"
+HINDSIGHT_API_KEY_ENV = "HINDSIGHT_API_KEY"
+
+
+@dataclass
+class HindsightLangGraphConfig:
+    """Connection and default settings for the LangGraph integration.
+
+    Attributes:
+        hindsight_api_url: URL of the Hindsight API server.
+        api_key: API key for Hindsight authentication.
+        budget: Default recall budget level (low/mid/high).
+        max_tokens: Default maximum tokens for recall results.
+        tags: Default tags applied when storing memories.
+        recall_tags: Default tags to filter when searching memories.
+        recall_tags_match: Tag matching mode (any/all/any_strict/all_strict).
+        verbose: Enable verbose logging.
+    """
+
+    hindsight_api_url: str = DEFAULT_HINDSIGHT_API_URL
+    api_key: Optional[str] = None
+    budget: str = "mid"
+    max_tokens: int = 4096
+    tags: Optional[list[str]] = None
+    recall_tags: Optional[list[str]] = None
+    recall_tags_match: str = "any"
+    verbose: bool = False
+
+
+_global_config: Optional[HindsightLangGraphConfig] = None
+
+
+def configure(
+    hindsight_api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    budget: str = "mid",
+    max_tokens: int = 4096,
+    tags: Optional[list[str]] = None,
+    recall_tags: Optional[list[str]] = None,
+    recall_tags_match: str = "any",
+    verbose: bool = False,
+) -> HindsightLangGraphConfig:
+    """Configure Hindsight connection and default settings.
+
+    Args:
+        hindsight_api_url: Hindsight API URL (default: production).
+        api_key: API key. Falls back to HINDSIGHT_API_KEY env var.
+        budget: Default recall budget (low/mid/high).
+        max_tokens: Default max tokens for recall.
+        tags: Default tags for retain operations.
+        recall_tags: Default tags to filter recall/search.
+        recall_tags_match: Tag matching mode.
+        verbose: Enable verbose logging.
+
+    Returns:
+        The configured HindsightLangGraphConfig.
+    """
+    global _global_config
+
+    resolved_url = hindsight_api_url or DEFAULT_HINDSIGHT_API_URL
+    resolved_key = api_key or os.environ.get(HINDSIGHT_API_KEY_ENV)
+
+    _global_config = HindsightLangGraphConfig(
+        hindsight_api_url=resolved_url,
+        api_key=resolved_key,
+        budget=budget,
+        max_tokens=max_tokens,
+        tags=tags,
+        recall_tags=recall_tags,
+        recall_tags_match=recall_tags_match,
+        verbose=verbose,
+    )
+
+    return _global_config
+
+
+def get_config() -> Optional[HindsightLangGraphConfig]:
+    """Get the current global configuration."""
+    return _global_config
+
+
+def reset_config() -> None:
+    """Reset global configuration to None."""
+    global _global_config
+    _global_config = None

hindsight_langgraph/errors.py

@@ -0,0 +1,7 @@
+"""Hindsight-LangGraph error types."""
+
+
+class HindsightError(Exception):
+    """Exception raised when a Hindsight memory operation fails."""
+
+    pass

hindsight_langgraph/nodes.py

@@ -0,0 +1,259 @@
+"""Pre-built LangGraph nodes for Hindsight memory operations.
+
+Provides node functions that can be added directly to a StateGraph to
+inject memories at conversation start and store new memories after responses.
+"""
+
+import logging
+from typing import Any, Optional
+
+from hindsight_client import Hindsight
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph import MessagesState
+
+from ._client import resolve_client
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_text_content(content: Any) -> str:
+    """Extract text from a message content field.
+
+    Handles both plain string content and multimodal content lists
+    (where each item may be a dict with "type" and "text" keys).
+    Returns the concatenated text parts, or an empty string if no
+    text content is found.
+    """
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for part in content:
+            if isinstance(part, str):
+                parts.append(part)
+            elif isinstance(part, dict) and part.get("type") == "text":
+                parts.append(part.get("text", ""))
+        return " ".join(parts)
+    return str(content) if content else ""
+
+
+def create_recall_node(
+    *,
+    bank_id: Optional[str] = None,
+    client: Optional[Hindsight] = None,
+    hindsight_api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    budget: str = "mid",
+    max_tokens: int = 4096,
+    max_results: int = 10,
+    tags: Optional[list[str]] = None,
+    tags_match: str = "any",
+    bank_id_from_config: str = "user_id",
+    output_key: Optional[str] = None,
+):
+    """Create a node that injects relevant memories into the conversation.
+
+    This node extracts the latest user message, recalls relevant memories
+    from Hindsight, and returns them either as a SystemMessage in the
+    ``messages`` list (default) or as a plain string under a custom state
+    key via ``output_key``.
+
+    **Message ordering:** When using the default ``messages`` output,
+    ``MessagesState`` uses ``add_messages`` as its reducer, which appends.
+    The memory SystemMessage will appear after existing messages, not at
+    position 0. If your LLM provider requires system messages first, use
+    ``output_key`` to write the memory text to a separate state field and
+    inject it into your prompt in the agent node.
+
+    Example with ``output_key`` (recommended for correct ordering)::
+
+        from typing import Optional
+        from langgraph.graph import MessagesState
+
+        class AgentState(MessagesState):
+            memory_context: Optional[str] = None
+
+        recall = create_recall_node(
+            client=client, bank_id="user-123", output_key="memory_context"
+        )
+        # In your agent node, read state["memory_context"] and prepend
+        # it to the system prompt.
+
+    The bank_id can be provided directly or resolved dynamically from
+    the graph's RunnableConfig via the ``bank_id_from_config`` key.
+
+    Args:
+        bank_id: Static Hindsight memory bank ID.
+        client: Pre-configured Hindsight client.
+        hindsight_api_url: API URL (used if no client provided).
+        api_key: API key (used if no client provided).
+        budget: Recall budget level (low/mid/high).
+        max_tokens: Maximum tokens for recall results.
+        max_results: Maximum number of memories to inject.
+        tags: Tags to filter recall results.
+        tags_match: Tag matching mode.
+        bank_id_from_config: Config key to read bank_id from at runtime.
+            Looked up in ``config["configurable"][bank_id_from_config]``.
+            Only used when ``bank_id`` is not provided.
+        output_key: If set, write the memory text to this state key as a
+            plain string instead of appending a SystemMessage to ``messages``.
+            Use this with a custom state type to control where memory context
+            appears in your prompt.
+
+    Returns:
+        An async node function compatible with LangGraph StateGraph.
+    """
+    resolved_client = resolve_client(client, hindsight_api_url, api_key)
+
+    async def recall_node(
+        state: MessagesState, config: Optional[RunnableConfig] = None
+    ) -> dict[str, Any]:
+        resolved_bank_id = bank_id
+        if resolved_bank_id is None and config:
+            configurable = config.get("configurable", {})
+            resolved_bank_id = configurable.get(bank_id_from_config)
+
+        if not resolved_bank_id:
+            logger.warning(
+                "No bank_id available for recall node, skipping memory injection."
+            )
+            if output_key:
+                return {output_key: None}
+            return {"messages": []}
+
+        # Extract query from the latest human message
+        query = None
+        for msg in reversed(state["messages"]):
+            if isinstance(msg, HumanMessage):
+                query = _extract_text_content(msg.content)
+                break
+
+        if not query:
+            if output_key:
+                return {output_key: None}
+            return {"messages": []}
+
+        try:
+            recall_kwargs: dict[str, Any] = {
+                "bank_id": resolved_bank_id,
+                "query": query,
+                "budget": budget,
+                "max_tokens": max_tokens,
+            }
+            if tags:
+                recall_kwargs["tags"] = tags
+                recall_kwargs["tags_match"] = tags_match
+
+            response = await resolved_client.arecall(**recall_kwargs)
+            results = response.results[:max_results] if response.results else []
+
+            if not results:
+                if output_key:
+                    return {output_key: None}
+                return {"messages": []}
+
+            lines = ["Relevant memories about this user:"]
+            for i, result in enumerate(results, 1):
+                lines.append(f"{i}. {result.text}")
+            memory_text = "\n".join(lines)
+
+            if output_key:
+                return {output_key: memory_text}
+            return {
+                "messages": [
+                    SystemMessage(content=memory_text, id="hindsight_memory_context")
+                ]
+            }
+        except Exception as e:
+            logger.error(f"Recall node failed: {e}")
+            if output_key:
+                return {output_key: None}
+            return {"messages": []}
+
+    return recall_node
+
+
+def create_retain_node(
+    *,
+    bank_id: Optional[str] = None,
+    client: Optional[Hindsight] = None,
+    hindsight_api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    tags: Optional[list[str]] = None,
+    bank_id_from_config: str = "user_id",
+    retain_human: bool = True,
+    retain_ai: bool = False,
+):
+    """Create a node that stores conversation messages as memories.
+
+    This node extracts messages from the conversation and stores them
+    via Hindsight retain. It should be placed after the LLM response
+    node in your graph.
+
+    Args:
+        bank_id: Static Hindsight memory bank ID.
+        client: Pre-configured Hindsight client.
+        hindsight_api_url: API URL (used if no client provided).
+        api_key: API key (used if no client provided).
+        tags: Tags to apply to stored memories.
+        bank_id_from_config: Config key to read bank_id from at runtime.
+        retain_human: Store human messages as memories.
+        retain_ai: Store AI responses as memories.
+
+    Returns:
+        An async node function compatible with LangGraph StateGraph.
+    """
+    resolved_client = resolve_client(client, hindsight_api_url, api_key)
+
+    async def retain_node(
+        state: MessagesState, config: Optional[RunnableConfig] = None
+    ) -> dict[str, Any]:
+        resolved_bank_id = bank_id
+        if resolved_bank_id is None and config:
+            configurable = config.get("configurable", {})
+            resolved_bank_id = configurable.get(bank_id_from_config)
+
+        if not resolved_bank_id:
+            logger.warning(
+                "No bank_id available for retain node, skipping memory storage."
+            )
+            return {"messages": []}
+
+        # Only retain the latest human and/or AI message to avoid
+        # duplicating memories that were already stored in prior calls.
+        messages_to_retain = []
+        if retain_human:
+            for msg in reversed(state["messages"]):
+                if isinstance(msg, HumanMessage):
+                    text = _extract_text_content(msg.content)
+                    if text:
+                        messages_to_retain.append(text)
+                    break
+        if retain_ai:
+            for msg in reversed(state["messages"]):
+                if isinstance(msg, AIMessage):
+                    text = _extract_text_content(msg.content)
+                    if text:
+                        messages_to_retain.append(text)
+                    break
+
+        if not messages_to_retain:
+            return {"messages": []}
+
+        content = "\n\n".join(messages_to_retain)
+
+        try:
+            retain_kwargs: dict[str, Any] = {
+                "bank_id": resolved_bank_id,
+                "content": content,
+            }
+            if tags:
+                retain_kwargs["tags"] = tags
+            await resolved_client.aretain(**retain_kwargs)
+        except Exception as e:
+            logger.error(f"Retain node failed: {e}")
+
+        return {"messages": []}
+
+    return retain_node

hindsight_langgraph/store.py

@@ -0,0 +1,430 @@
+"""LangGraph BaseStore adapter backed by Hindsight.
+
+Maps LangGraph's key-value store interface to Hindsight's memory operations.
+Namespace tuples are joined to form bank IDs, and values are stored/retrieved
+via retain/recall.
+"""
+
+import asyncio
+import hashlib
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any, Iterable, Optional
+
+from hindsight_client import Hindsight
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    Item,
+    ListNamespacesOp,
+    PutOp,
+    Result,
+    SearchItem,
+    SearchOp,
+)
+
+from ._client import resolve_client
+from .errors import HindsightError
+
+logger = logging.getLogger(__name__)
+
+
+def _namespace_to_bank_id(namespace: tuple[str, ...]) -> str:
+    """Convert a namespace tuple to a Hindsight bank ID.
+
+    Uses "." as separator since "/" is not valid in Hindsight bank IDs
+    (interpreted as URL path segments).
+    """
+    return ".".join(namespace) if namespace else "default"
+
+
+def _make_item(
+    namespace: tuple[str, ...],
+    key: str,
+    value: dict,
+    created_at: Optional[datetime] = None,
+) -> Item:
+    """Create a LangGraph Item from Hindsight data."""
+    now = datetime.now(timezone.utc)
+    return Item(
+        namespace=namespace,
+        key=key,
+        value=value,
+        created_at=created_at or now,
+        updated_at=now,
+    )
+
+
+def _make_search_item(
+    namespace: tuple[str, ...],
+    key: str,
+    value: dict,
+    score: float,
+    created_at: Optional[datetime] = None,
+) -> SearchItem:
+    """Create a LangGraph SearchItem from Hindsight recall results."""
+    now = datetime.now(timezone.utc)
+    return SearchItem(
+        namespace=namespace,
+        key=key,
+        value=value,
+        score=score,
+        created_at=created_at or now,
+        updated_at=now,
+    )
+
+
+class HindsightStore(BaseStore):
+    """LangGraph BaseStore implementation backed by Hindsight.
+
+    Maps LangGraph's namespace/key-value model to Hindsight memory banks:
+    - Namespace tuples are joined with "." to form bank IDs
+    - ``put()`` stores values via Hindsight retain with the key as document_id
+    - ``search()`` uses Hindsight recall for semantic search
+    - ``get()`` uses recall with the key as a targeted query, returning only
+      exact ``document_id`` matches. If the stored document does not surface in
+      the recall window, ``get()`` returns ``None`` even though the item exists.
+      Hindsight does not currently expose a direct document-lookup endpoint.
+
+    **Known limitations:**
+
+    - **Async-only.** All sync methods (``batch``, ``get``, ``put``, ``delete``,
+      ``search``, ``list_namespaces``) raise ``NotImplementedError``. Use the
+      async variants (``abatch``, ``aget``, ``aput``, ``adelete``, ``asearch``,
+      ``alist_namespaces``) instead.
+    - **``list_namespaces`` is session-scoped.** It only tracks namespaces that
+      have been written to via ``aput()`` during the current process. After a
+      restart, ``list_namespaces`` returns empty even though data still exists
+      in Hindsight. Hindsight does not currently provide a bank-listing API.
+    - **``delete`` is a no-op.** Calling ``adelete()`` logs a debug message but
+      does not remove data. Hindsight's memory model is append-oriented; fact
+      superseding is handled automatically during retain.
+    - **``get()`` relies on recall.** There is no direct key lookup — the key
+      is used as a recall query and only exact ``document_id`` matches are
+      returned. Items that do not rank in the top recall results will appear
+      missing.
+
+    Example::
+
+        from hindsight_client import Hindsight
+        from hindsight_langgraph import HindsightStore
+
+        store = HindsightStore(client=Hindsight(base_url="http://localhost:8888"))
+        graph = builder.compile(checkpointer=checkpointer, store=store)
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Optional[Hindsight] = None,
+        hindsight_api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+    ):
+        self._client = resolve_client(client, hindsight_api_url, api_key)
+        self._tags = tags
+        # Track known namespaces for list_namespaces (session-scoped only)
+        self._known_namespaces: set[tuple[str, ...]] = set()
+        # Track banks that have been created to avoid repeated create calls
+        self._created_banks: set[str] = set()
+        # Per-bank locks for concurrency-safe bank creation
+        self._bank_locks: dict[str, asyncio.Lock] = {}
+
+    def batch(
+        self, ops: Iterable[GetOp | PutOp | SearchOp | ListNamespacesOp]
+    ) -> list[Result]:
+        raise NotImplementedError("Use abatch() for async operation.")
+
+    async def abatch(
+        self, ops: Iterable[GetOp | PutOp | SearchOp | ListNamespacesOp]
+    ) -> list[Result]:
+        results: list[Result] = []
+        for op in ops:
+            if isinstance(op, GetOp):
+                results.append(await self._handle_get(op))
+            elif isinstance(op, PutOp):
+                await self._handle_put(op)
+                results.append(None)
+            elif isinstance(op, SearchOp):
+                results.append(await self._handle_search(op))
+            elif isinstance(op, ListNamespacesOp):
+                results.append(await self._handle_list_namespaces(op))
+            else:
+                results.append(None)
+        return results
+
+    async def _handle_get(self, op: GetOp) -> Optional[Item]:
+        """Handle a get operation by recalling with the key as query."""
+        bank_id = _namespace_to_bank_id(op.namespace)
+        try:
+            await self._ensure_bank(bank_id)
+            response = await self._client.arecall(
+                bank_id=bank_id,
+                query=op.key,
+                budget="low",
+                max_tokens=1024,
+            )
+            if not response.results:
+                return None
+
+            # Only return a result if the document_id matches the requested key exactly.
+            # Do NOT fall back to semantic search — that would violate key-value store semantics.
+            for result in response.results:
+                doc_id = getattr(result, "document_id", None)
+                if doc_id == op.key:
+                    value = _parse_value(result.text)
+                    ts = getattr(result, "occurred_start", None)
+                    return _make_item(op.namespace, op.key, value, created_at=ts)
+
+            return None
+        except Exception as e:
+            logger.error(f"Store get failed for {op.namespace}/{op.key}: {e}")
+            return None
+
+    async def _ensure_bank(self, bank_id: str) -> None:
+        """Create a bank if it hasn't been created yet in this session.
+
+        Uses per-bank locking to prevent concurrent creation races.
+        """
+        if bank_id in self._created_banks:
+            return
+        lock = self._bank_locks.setdefault(bank_id, asyncio.Lock())
+        async with lock:
+            # Double-check after acquiring the lock
+            if bank_id in self._created_banks:
+                return
+            try:
+                await self._client.acreate_bank(bank_id, name=bank_id)
+                self._created_banks.add(bank_id)
+            except Exception as e:
+                error_str = str(e).lower()
+                if (
+                    "already exists" in error_str
+                    or "conflict" in error_str
+                    or "409" in error_str
+                ):
+                    # Bank already exists — safe to cache
+                    self._created_banks.add(bank_id)
+                else:
+                    logger.error(f"Failed to create bank '{bank_id}': {e}")
+                    raise
+
+    async def _handle_put(self, op: PutOp) -> None:
+        """Handle a put operation by retaining the value."""
+        bank_id = _namespace_to_bank_id(op.namespace)
+        self._known_namespaces.add(op.namespace)
+
+        if op.value is None:
+            # LangGraph uses value=None as delete
+            logger.debug(f"Delete not supported for {op.namespace}/{op.key}, skipping.")
+            return
+
+        try:
+            await self._ensure_bank(bank_id)
+            content = (
+                json.dumps(op.value) if isinstance(op.value, dict) else str(op.value)
+            )
+            retain_kwargs: dict[str, Any] = {
+                "bank_id": bank_id,
+                "content": content,
+                "document_id": op.key,
+            }
+            if self._tags:
+                retain_kwargs["tags"] = self._tags
+            await self._client.aretain(**retain_kwargs)
+        except Exception as e:
+            logger.error(f"Store put failed for {op.namespace}/{op.key}: {e}")
+            raise HindsightError(f"Store put failed: {e}") from e
+
+    async def _handle_search(self, op: SearchOp) -> list[SearchItem]:
+        """Handle a search operation via Hindsight recall."""
+        bank_id = _namespace_to_bank_id(op.namespace_prefix)
+        query = op.query or "*"
+
+        try:
+            await self._ensure_bank(bank_id)
+            recall_kwargs: dict[str, Any] = {
+                "bank_id": bank_id,
+                "query": query,
+                "budget": "mid",
+                "max_tokens": 4096,
+            }
+            response = await self._client.arecall(**recall_kwargs)
+            if not response.results:
+                return []
+
+            # Build all candidate items first
+            all_items = []
+            for i, result in enumerate(response.results):
+                value = _parse_value(result.text)
+                doc_id = getattr(result, "document_id", None) or _content_key(
+                    result.text
+                )
+                score = max(
+                    0.0, 1.0 - (i * 0.01)
+                )  # Approximate score from rank position
+                ts = getattr(result, "occurred_start", None)
+                all_items.append(
+                    _make_search_item(
+                        op.namespace_prefix, doc_id, value, score=score, created_at=ts
+                    )
+                )
+
+            # Apply filters BEFORE pagination so offset/limit operate on
+            # the filtered set rather than discarding matching items.
+            if op.filter:
+                all_items = [
+                    item for item in all_items if _matches_filter(item.value, op.filter)
+                ]
+
+            limit = op.limit or 10
+            offset = op.offset or 0
+            return all_items[offset : offset + limit]
+        except Exception as e:
+            logger.error(f"Store search failed for {op.namespace_prefix}: {e}")
+            return []
+
+    async def _handle_list_namespaces(
+        self, op: ListNamespacesOp
+    ) -> list[tuple[str, ...]]:
+        """List known namespaces. Limited to namespaces seen via put() in this session."""
+        namespaces = list(self._known_namespaces)
+
+        if op.match_conditions:
+            filtered = []
+            for ns in namespaces:
+                match = True
+                for cond in op.match_conditions:
+                    match_type = getattr(cond, "match_type", "prefix")
+                    if match_type == "prefix":
+                        if not _namespace_starts_with(ns, cond.path):
+                            match = False
+                            break
+                    elif match_type == "suffix":
+                        if not _namespace_ends_with(ns, cond.path):
+                            match = False
+                            break
+                if match:
+                    filtered.append(ns)
+            namespaces = filtered
+
+        if op.max_depth is not None:
+            # Truncate namespaces to max_depth and deduplicate, per BaseStore contract.
+            namespaces = list(dict.fromkeys(ns[: op.max_depth] for ns in namespaces))
+
+        limit = op.limit or 100
+        offset = op.offset or 0
+        return namespaces[offset : offset + limit]
+
+    # Sync convenience methods that delegate to async
+
+    def get(self, namespace: tuple[str, ...], key: str) -> Optional[Item]:
+        raise NotImplementedError("Use aget() for async operation.")
+
+    async def aget(self, namespace: tuple[str, ...], key: str) -> Optional[Item]:
+        result = await self.abatch([GetOp(namespace=namespace, key=key)])
+        return result[0]
+
+    def put(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+        value: dict,
+        index: Optional[Any] = None,
+    ) -> None:
+        raise NotImplementedError("Use aput() for async operation.")
+
+    async def aput(
+        self,
+        namespace: tuple[str, ...],
+        key: str,
+        value: dict,
+        index: Optional[Any] = None,
+        ttl: Optional[float] = None,
+    ) -> None:
+        # ttl is accepted for BaseStore compatibility but not used;
+        # Hindsight does not support TTL-based expiration natively.
+        await self.abatch([PutOp(namespace=namespace, key=key, value=value)])
+
+    def delete(self, namespace: tuple[str, ...], key: str) -> None:
+        raise NotImplementedError("Use adelete() for async operation.")
+
+    async def adelete(self, namespace: tuple[str, ...], key: str) -> None:
+        await self.abatch([PutOp(namespace=namespace, key=key, value=None)])
+
+    def search(
+        self,
+        namespace_prefix: tuple[str, ...],
+        *,
+        query: Optional[str] = None,
+        filter: Optional[dict] = None,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> list[SearchItem]:
+        raise NotImplementedError("Use asearch() for async operation.")
+
+    async def asearch(
+        self,
+        namespace_prefix: tuple[str, ...],
+        *,
+        query: Optional[str] = None,
+        filter: Optional[dict] = None,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> list[SearchItem]:
+        result = await self.abatch(
+            [
+                SearchOp(
+                    namespace_prefix=namespace_prefix,
+                    query=query,
+                    filter=filter,
+                    limit=limit,
+                    offset=offset,
+                )
+            ]
+        )
+        return result[0]
+
+    # list_namespaces / alist_namespaces are NOT overridden here.
+    # The base class converts prefix=/suffix= kwargs into MatchCondition
+    # objects and calls abatch() -> _handle_list_namespaces(). Overriding
+    # with a different signature (match_conditions=) would break callers.
+
+
+def _parse_value(text: str) -> dict:
+    """Try to parse stored text as JSON, fallback to wrapping in a dict."""
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict):
+            return parsed
+    except (json.JSONDecodeError, TypeError):
+        pass
+    return {"text": text}
+
+
+def _content_key(text: str) -> str:
+    """Generate a stable key from content text."""
+    return hashlib.sha256(text.encode()).hexdigest()[:12]
+
+
+def _matches_filter(value: dict, filter_dict: dict) -> bool:
+    """Check if a value dict matches all filter conditions."""
+    for key, expected in filter_dict.items():
+        if value.get(key) != expected:
+            return False
+    return True
+
+
+def _namespace_starts_with(namespace: tuple[str, ...], prefix: tuple[str, ...]) -> bool:
+    """Check if namespace starts with the given prefix."""
+    if len(prefix) > len(namespace):
+        return False
+    return namespace[: len(prefix)] == prefix
+
+
+def _namespace_ends_with(namespace: tuple[str, ...], suffix: tuple[str, ...]) -> bool:
+    """Check if namespace ends with the given suffix."""
+    if len(suffix) > len(namespace):
+        return False
+    return namespace[len(namespace) - len(suffix) :] == suffix

hindsight_langgraph/tools.py

@@ -0,0 +1,217 @@
+"""LangGraph tool definitions for Hindsight memory operations.
+
+Provides factory functions that create LangGraph-compatible tool functions
+backed by Hindsight's retain/recall/reflect APIs. These tools can be bound
+to a ChatModel via `model.bind_tools()` or used in a ToolNode.
+"""
+
+import logging
+from typing import Any, Optional
+
+from hindsight_client import Hindsight
+from langchain_core.tools import tool
+
+from ._client import resolve_client
+from .config import get_config
+from .errors import HindsightError
+
+logger = logging.getLogger(__name__)
+
+
+def create_hindsight_tools(
+    *,
+    bank_id: str,
+    client: Optional[Hindsight] = None,
+    hindsight_api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    budget: Optional[str] = None,
+    max_tokens: Optional[int] = None,
+    tags: Optional[list[str]] = None,
+    recall_tags: Optional[list[str]] = None,
+    recall_tags_match: Optional[str] = None,
+    # Retain options
+    retain_metadata: Optional[dict[str, str]] = None,
+    retain_document_id: Optional[str] = None,
+    # Recall options
+    recall_types: Optional[list[str]] = None,
+    recall_include_entities: bool = False,
+    # Reflect options
+    reflect_context: Optional[str] = None,
+    reflect_max_tokens: Optional[int] = None,
+    reflect_response_schema: Optional[dict[str, Any]] = None,
+    reflect_tags: Optional[list[str]] = None,
+    reflect_tags_match: Optional[str] = None,
+    include_retain: bool = True,
+    include_recall: bool = True,
+    include_reflect: bool = True,
+) -> list:
+    """Create Hindsight memory tools for a LangGraph agent.
+
+    Returns a list of LangChain tool instances compatible with LangGraph's
+    ToolNode and ChatModel.bind_tools().
+
+    Args:
+        bank_id: The Hindsight memory bank to operate on.
+        client: Pre-configured Hindsight client (preferred).
+        hindsight_api_url: API URL (used if no client provided).
+        api_key: API key (used if no client provided).
+        budget: Recall/reflect budget level (low/mid/high).
+        max_tokens: Maximum tokens for recall results.
+        tags: Tags applied when storing memories via retain.
+        recall_tags: Tags to filter when searching memories.
+        recall_tags_match: Tag matching mode (any/all/any_strict/all_strict).
+        retain_metadata: Default metadata dict for retain operations.
+        retain_document_id: Default document_id for retain (groups/upserts memories).
+        recall_types: Fact types to filter (world, experience, opinion, observation).
+        recall_include_entities: Include entity information in recall results.
+        reflect_context: Additional context for reflect operations.
+        reflect_max_tokens: Max tokens for reflect results (defaults to max_tokens).
+        reflect_response_schema: JSON schema to constrain reflect output format.
+        reflect_tags: Tags to filter memories used in reflect (defaults to recall_tags).
+        reflect_tags_match: Tag matching for reflect (defaults to recall_tags_match).
+        include_retain: Include the retain (store) tool.
+        include_recall: Include the recall (search) tool.
+        include_reflect: Include the reflect (synthesize) tool.
+
+    Returns:
+        List of LangChain tool instances.
+
+    Raises:
+        HindsightError: If no client or API URL can be resolved.
+    """
+    resolved_client = resolve_client(client, hindsight_api_url, api_key)
+
+    config = get_config()
+    effective_tags = tags if tags is not None else (config.tags if config else None)
+    effective_recall_tags = (
+        recall_tags
+        if recall_tags is not None
+        else (config.recall_tags if config else None)
+    )
+    effective_recall_tags_match = (
+        recall_tags_match
+        if recall_tags_match is not None
+        else (config.recall_tags_match if config else "any")
+    )
+    effective_budget = (
+        budget if budget is not None else (config.budget if config else "mid")
+    )
+    effective_max_tokens = (
+        max_tokens
+        if max_tokens is not None
+        else (config.max_tokens if config else 4096)
+    )
+
+    tools: list = []
+
+    if include_retain:
+
+        @tool
+        async def hindsight_retain(content: str) -> str:
+            """Store information to long-term memory for later retrieval.
+
+            Use this to save important facts, user preferences, decisions,
+            or any information that should be remembered across conversations.
+
+            Args:
+                content: The information to store in memory.
+            """
+            try:
+                retain_kwargs: dict[str, Any] = {"bank_id": bank_id, "content": content}
+                if effective_tags:
+                    retain_kwargs["tags"] = effective_tags
+                if retain_metadata:
+                    retain_kwargs["metadata"] = retain_metadata
+                if retain_document_id:
+                    retain_kwargs["document_id"] = retain_document_id
+                await resolved_client.aretain(**retain_kwargs)
+                return "Memory stored successfully."
+            except Exception as e:
+                logger.error(f"Retain failed: {e}")
+                raise HindsightError(f"Retain failed: {e}") from e
+
+        tools.append(hindsight_retain)
+
+    if include_recall:
+
+        @tool
+        async def hindsight_recall(query: str) -> str:
+            """Search long-term memory for relevant information.
+
+            Use this to find previously stored facts, preferences, or context.
+            Returns a numbered list of matching memories.
+
+            Args:
+                query: What to search for in memory.
+            """
+            try:
+                recall_kwargs: dict[str, Any] = {
+                    "bank_id": bank_id,
+                    "query": query,
+                    "budget": effective_budget,
+                    "max_tokens": effective_max_tokens,
+                }
+                if effective_recall_tags:
+                    recall_kwargs["tags"] = effective_recall_tags
+                    recall_kwargs["tags_match"] = effective_recall_tags_match
+                if recall_types:
+                    recall_kwargs["types"] = recall_types
+                if recall_include_entities:
+                    recall_kwargs["include_entities"] = True
+                response = await resolved_client.arecall(**recall_kwargs)
+                if not response.results:
+                    return "No relevant memories found."
+                lines = []
+                for i, result in enumerate(response.results, 1):
+                    lines.append(f"{i}. {result.text}")
+                return "\n".join(lines)
+            except Exception as e:
+                logger.error(f"Recall failed: {e}")
+                raise HindsightError(f"Recall failed: {e}") from e
+
+        tools.append(hindsight_recall)
+
+    if include_reflect:
+
+        @tool
+        async def hindsight_reflect(query: str) -> str:
+            """Synthesize a thoughtful answer from long-term memories.
+
+            Use this when you need a coherent summary or reasoned response
+            about what you know, rather than raw memory facts.
+
+            Args:
+                query: The question to reflect on using stored memories.
+            """
+            try:
+                reflect_kwargs: dict[str, Any] = {
+                    "bank_id": bank_id,
+                    "query": query,
+                    "budget": effective_budget,
+                }
+                if reflect_context:
+                    reflect_kwargs["context"] = reflect_context
+                effective_reflect_max = reflect_max_tokens or effective_max_tokens
+                if effective_reflect_max:
+                    reflect_kwargs["max_tokens"] = effective_reflect_max
+                if reflect_response_schema:
+                    reflect_kwargs["response_schema"] = reflect_response_schema
+                # Reflect tags: use reflect-specific or fall back to recall tags
+                effective_reflect_tags = (
+                    reflect_tags if reflect_tags is not None else effective_recall_tags
+                )
+                effective_reflect_tags_match = (
+                    reflect_tags_match or effective_recall_tags_match
+                )
+                if effective_reflect_tags:
+                    reflect_kwargs["tags"] = effective_reflect_tags
+                    reflect_kwargs["tags_match"] = effective_reflect_tags_match
+                response = await resolved_client.areflect(**reflect_kwargs)
+                return response.text or "No relevant memories found."
+            except Exception as e:
+                logger.error(f"Reflect failed: {e}")
+                raise HindsightError(f"Reflect failed: {e}") from e
+
+        tools.append(hindsight_reflect)
+
+    return tools

hindsight_langgraph-0.1.1.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: hindsight-langgraph
+Version: 0.1.1
+Summary: LangGraph integration for Hindsight - persistent memory tools, nodes, and store for AI agents
+Project-URL: Homepage, https://github.com/vectorize-io/hindsight
+Project-URL: Documentation, https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/langgraph
+Project-URL: Repository, https://github.com/vectorize-io/hindsight
+Author-email: Vectorize <support@vectorize.io>
+License: MIT
+Keywords: agents,ai,hindsight,langchain,langgraph,memory
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: hindsight-client>=0.4.0
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: all
+Requires-Dist: langgraph>=0.3.0; extra == 'all'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.3.0; extra == 'langgraph'

hindsight_langgraph-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+hindsight_langgraph/__init__.py,sha256=4zYHuK9cpE0avkrCzPBL4Fqh-qH24wnOt-78RvcTj74,2934
+hindsight_langgraph/_client.py,sha256=BVneZXQXfVewCxfElOJ2u1ejEKlIbaUjzxXCyC8XA4I,923
+hindsight_langgraph/config.py,sha256=qVW7H006hbGQ9YFeIvN_7rufeGh_BnbGMWLNWiWBdN8,2867
+hindsight_langgraph/errors.py,sha256=tn9hA-mH63fF9NipRZKbxvcTf-M2OP8WhaFccUYdthc,152
+hindsight_langgraph/nodes.py,sha256=CwHBOLN63WDuQ998LA_3pSNv6mgE_-5r7ikIDyoTxEY,9485
+hindsight_langgraph/store.py,sha256=clF3C2wRXs8SVI8rjw6I41WN-njdYIkudqiKN5lXJys,15717
+hindsight_langgraph/tools.py,sha256=NDkZMETg-bCqCKgYWmPYBRg0mmiBlLKpwTSIz7uGxOY,8788
+hindsight_langgraph-0.1.1.dist-info/METADATA,sha256=_DLuExAKWVxnY-YFYtNPdYN-KOJDklR3sq8e16PjR8A,1186
+hindsight_langgraph-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hindsight_langgraph-0.1.1.dist-info/RECORD,,

hindsight_langgraph-0.1.1.dist-info/WHEEL

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