langchain-membase 0.1.0__py3-none-any.whl

langchain_membase/__init__.py

@@ -0,0 +1,49 @@
+"""Membase long-term memory for LangChain and LangGraph."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ._common import DEFAULT_RECALL_TIMEOUT, MissingUserIdError
+from .retrievers import MembaseRetriever, MembaseUnavailableError
+from .tools import (
+    MembaseProfileTool,
+    MembaseSaveTool,
+    MembaseSearchTool,
+    MembaseToolkit,
+    membase_tools,
+)
+
+if TYPE_CHECKING:
+    from .middleware import MembaseRecallMiddleware
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_RECALL_TIMEOUT",
+    "MembaseProfileTool",
+    "MembaseRecallMiddleware",
+    "MembaseRetriever",
+    "MembaseSaveTool",
+    "MembaseSearchTool",
+    "MembaseToolkit",
+    "MembaseUnavailableError",
+    "MissingUserIdError",
+    "membase_tools",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # The middleware needs `langchain` (the `agents` extra); importing the package must not.
+    if name == "MembaseRecallMiddleware":
+        try:
+            from .middleware import MembaseRecallMiddleware
+        except ImportError as e:
+            raise ImportError(
+                "MembaseRecallMiddleware needs LangChain v1: "
+                "pip install 'langchain-membase[agents]'"
+            ) from e
+
+        return MembaseRecallMiddleware
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

langchain_membase/_common.py

@@ -0,0 +1,248 @@
+"""Shared plumbing: which client serves a call, how errors read, how recall is formatted."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import threading
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any, TypeVar
+
+from membase import Membase
+from membase.errors import (
+    APIConnectionError,
+    APITimeoutError,
+    MembaseError,
+    PermissionDeniedError,
+)
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+logger = logging.getLogger("langchain_membase")
+
+ClientFor = Callable[[str], Membase]
+"""Returns the Membase client of one end user: their own key, or their own local directory."""
+
+T = TypeVar("T")
+
+# The package's own default: it does not depend on which SDK release is installed.
+DEFAULT_BASE_URL = "https://api.app.membase.com"
+
+DEFAULT_RECALL_TIMEOUT = 8.0
+"""Budget, in seconds, for automatic per-turn recall. Explicit tool calls use the SDK's own."""
+
+
+class MissingUserIdError(ValueError):
+    """``client_for`` is set but the call carried no user id, so no client may serve it."""
+
+
+def build_client(
+    api_key: str | SecretStr | None = None,
+    base_url: str | None = None,
+    local: str | os.PathLike | bool | None = None,
+) -> Membase:
+    """A Membase client from the usual arguments, falling back to ``MEMBASE_API_KEY``."""
+    key = api_key.get_secret_value() if isinstance(api_key, SecretStr) else api_key
+    base_url = base_url or os.environ.get("MEMBASE_BASE_URL") or DEFAULT_BASE_URL
+    return Membase(api_key=key, base_url=base_url, local=local)
+
+
+class MembaseClientMixin(BaseModel):
+    """Fields every Membase object takes: one ready client, or ``client_for`` for many users."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: Membase | None = Field(default=None, exclude=True, repr=False)
+    """A ready Membase client. One client serves every call: right for a personal agent."""
+    client_for: ClientFor | None = Field(default=None, exclude=True, repr=False)
+    """``user_id -> Membase`` for a multi-user app; the user id comes from the run's config."""
+    api_key: SecretStr | None = Field(default=None, exclude=True, repr=False)
+    """Membase API key; defaults to ``MEMBASE_API_KEY``. Used when no ``client`` is given."""
+    base_url: str | None = None
+    """API base URL; defaults to ``MEMBASE_BASE_URL`` or ``https://api.app.membase.com``."""
+    local: str | Path | bool | None = Field(default=None, exclude=True)
+    """Run the Membase API in-process on this directory (``True`` = ``~/.membase``)."""
+
+    @model_validator(mode="after")
+    def _one_way_to_reach_memory(self) -> MembaseClientMixin:
+        if self.client_for is not None:
+            if self.client is not None or self.api_key is not None or self.local:
+                raise ValueError(
+                    "pass either client_for (one client per user) or client / api_key / local "
+                    "(one client for every call), not both"
+                )
+            return self
+        if self.client is None:
+            self.client = build_client(self.api_key, self.base_url, self.local or None)
+        return self
+
+    def _membase(self, user_id: str | None) -> Membase:
+        return resolve_client(self.client, self.client_for, user_id)
+
+
+def resolve_client(
+    client: Membase | None, client_for: ClientFor | None, user_id: str | None
+) -> Membase:
+    """The client for this call. With ``client_for`` a user id is mandatory: no fallback client."""
+    if client_for is not None:
+        if not user_id:
+            raise MissingUserIdError(
+                "client_for is set, so every call needs the end user's id: pass "
+                "config={'configurable': {'user_id': ...}} (or a LangGraph context with user_id)"
+            )
+        return client_for(user_id)
+    if client is None:  # pragma: no cover - the validator always sets one
+        raise ValueError("no Membase client configured")
+    if user_id:
+        _warn_single_client_once()
+    return client
+
+
+_warned_single_client = False
+
+
+def _warn_single_client_once() -> None:
+    global _warned_single_client
+    if not _warned_single_client:
+        _warned_single_client = True
+        logger.warning(
+            "a user_id reached langchain-membase but no client_for is set, so one Membase key "
+            "serves every user. That suits a personal agent only; a multi-user app must pass "
+            "client_for so each person's call uses their own key."
+        )
+
+
+def user_id_from(config: Mapping[str, Any] | None = None, context: Any = None) -> str | None:
+    """The end user's id: ``configurable.user_id`` first, then a LangGraph runtime context."""
+    configurable = (config or {}).get("configurable") or {}
+    uid = configurable.get("user_id")
+    if uid in (None, "") and context is None:
+        context = _langgraph_context()
+    if uid in (None, "") and context is not None:
+        uid = (
+            context.get("user_id")
+            if isinstance(context, Mapping)
+            else getattr(context, "user_id", None)
+        )
+    return str(uid) if uid not in (None, "") else None
+
+
+def _langgraph_context() -> Any:
+    try:
+        from langgraph.runtime import get_runtime
+    except ImportError:
+        return None
+    try:
+        return get_runtime().context
+    except Exception:  # noqa: BLE001 - outside a graph run there is simply no context
+        return None
+
+
+def describe_error(e: BaseException) -> str:
+    """One actionable sentence for the model and the logs."""
+    if isinstance(e, PermissionDeniedError):
+        return (
+            f"Membase refused this request (403): {e.message}. This Membase key was narrowed or "
+            "revoked by its owner (a Memory switched off, an access level too low for this "
+            "action, or the key revoked); do not retry with this key."
+        )
+    if isinstance(e, APITimeoutError):
+        return (
+            "Membase did not answer in time; the user's memory may still be waking up after a "
+            "quiet spell. Try again in a moment."
+        )
+    if isinstance(e, APIConnectionError):
+        return f"Could not reach Membase: {e.message}."
+    if isinstance(e, MembaseError):
+        return f"Membase error: {e}"
+    return f"{type(e).__name__}: {e}"
+
+
+def unavailable(resp: Mapping[str, Any]) -> list[str]:
+    """``name: error`` for every Memory that could not answer a search."""
+    out = []
+    for c in resp.get("containers") or []:
+        if c.get("error"):
+            out.append(f"{c.get('name') or c.get('id')}: {c['error']}")
+    return out
+
+
+def format_passages(results: list[Mapping[str, Any]]) -> str:
+    """One line per passage, each citing the Memory (container) it came from."""
+    lines = []
+    for r in results:
+        name = r.get("container_name") or r.get("container") or "Membase"
+        content = str(r.get("content") or "").strip()
+        if content:
+            lines.append(f"- [{name}] {content}")
+    return "\n".join(lines)
+
+
+def format_search(resp: Mapping[str, Any]) -> str:
+    """Passages with their Memory, plus any Memory that could not answer (never 'no memory')."""
+    body = format_passages(resp.get("results") or [])
+    failed = unavailable(resp)
+    note = ""
+    if failed:
+        note = "These Memories could not answer, so what they hold is unknown: " + "; ".join(failed)
+    if body:
+        return body + (f"\n\n{note}" if note else "")
+    if note:
+        return "No passages came back. " + note
+    return "No matching memories."
+
+
+def call_with_budget(fn: Callable[[], T], timeout: float) -> T:
+    """Run ``fn`` but stop waiting after ``timeout`` seconds (raises ``TimeoutError``).
+
+    The call keeps running on a daemon thread; letting it finish wakes the user's memory, so
+    the next turn is fast. A daemon thread never holds up interpreter exit.
+    """
+    box: dict[str, Any] = {}
+    done = threading.Event()
+
+    def run() -> None:
+        try:
+            box["value"] = fn()
+        except BaseException as e:  # noqa: BLE001 - re-raised on the caller's thread
+            box["error"] = e
+        finally:
+            done.set()
+
+    threading.Thread(target=run, name="membase-recall", daemon=True).start()
+    if not done.wait(timeout):
+        raise TimeoutError(f"Membase recall took longer than {timeout:g}s")
+    if "error" in box:
+        raise box["error"]
+    return box["value"]
+
+
+async def acall_with_budget(fn: Callable[[], T], timeout: float) -> T:
+    """``call_with_budget`` for an event loop: the blocking SDK call runs off the loop."""
+    loop = asyncio.get_running_loop()
+    fut: asyncio.Future[T] = loop.create_future()
+
+    def settle(value: Any = None, error: BaseException | None = None) -> None:
+        if fut.done():
+            return
+        if error is not None:
+            fut.set_exception(error)
+        else:
+            fut.set_result(value)
+
+    def run() -> None:
+        try:
+            value, error = fn(), None
+        except BaseException as e:  # noqa: BLE001 - handed to the awaiting coroutine
+            value, error = None, e
+        try:
+            loop.call_soon_threadsafe(settle, value, error)
+        except RuntimeError:  # the loop closed while the call was still running
+            pass
+
+    threading.Thread(target=run, name="membase-recall", daemon=True).start()
+    try:
+        return await asyncio.wait_for(fut, timeout)
+    except asyncio.TimeoutError:
+        raise TimeoutError(f"Membase recall took longer than {timeout:g}s") from None

langchain_membase/middleware.py

@@ -0,0 +1,246 @@
+"""MembaseRecallMiddleware: time-boxed recall before the model call of a ``create_agent`` agent.
+
+Needs ``langchain>=1.1`` (``pip install 'langchain-membase[agents]'``).
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage
+from membase import Membase
+
+from ._common import (
+    DEFAULT_RECALL_TIMEOUT,
+    ClientFor,
+    acall_with_budget,
+    build_client,
+    call_with_budget,
+    describe_error,
+    format_passages,
+    logger,
+    resolve_client,
+    unavailable,
+    user_id_from,
+)
+
+RECALL_HEADER = (
+    "## From the user's memory (Membase)\n"
+    "Passages that may be relevant to the user's latest message, each with the Memory it came "
+    "from in [brackets]. Use them only if they help, and cite the Memory when you do."
+)
+
+_CACHE_SIZE = 512
+
+
+class MembaseRecallMiddleware(AgentMiddleware):
+    """Searches Membase once per user message and adds what it finds to the system message.
+
+    * Recall is automatic, so it is time-boxed (``timeout``, 8 s by default) and fails open:
+      on a timeout, a refused key or any other error it logs and the model runs without memory.
+      A search that ran past the budget keeps going in the background, which wakes the user's
+      memory for the next turn.
+    * The search runs on the first model call after a user message; the model calls that follow
+      tool calls in the same turn reuse its result.
+    * The recall goes into the request's system message only; it is never written to the
+      agent's state or checkpoint.
+    * ``capture_turns=True`` (off by default) saves the user's own message(s) of each turn,
+      once, as a note in ``container``; assistant replies are never saved. Writing is
+      otherwise left to ``MembaseSaveTool``.
+
+    Multi-user: pass ``client_for``; the user id comes from the run context
+    (``context_schema`` with ``user_id``) or ``config["configurable"]["user_id"]``.
+    """
+
+    def __init__(
+        self,
+        client: Membase | None = None,
+        *,
+        client_for: ClientFor | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        local: str | os.PathLike | bool | None = None,
+        container: str | None = None,
+        k: int | None = 5,
+        timeout: float = DEFAULT_RECALL_TIMEOUT,
+        capture_turns: bool = False,
+        header: str = RECALL_HEADER,
+    ) -> None:
+        super().__init__()
+        if client_for is not None and (client is not None or api_key or local):
+            raise ValueError("pass either client_for or client / api_key / local, not both")
+        if client_for is None and client is None:
+            client = build_client(api_key, base_url, local)
+        self.client = client
+        self.client_for = client_for
+        self.container = container
+        self.k = k
+        self.timeout = timeout
+        self.capture_turns = capture_turns
+        self.header = header
+        self._cache: OrderedDict[tuple[str, str], str] = OrderedDict()
+        self._lock = threading.Lock()
+
+    # -- model call -------------------------------------------------------------------------
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        key = self._turn_key(request)
+        if key is None:
+            return handler(request)
+        recall = self._cached(key)
+        if recall is None:
+            recall = self._recall(lambda: self._search(key[0], key[2]))
+            self._remember(key, recall)
+        return handler(self._with_recall(request, recall))
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelResponse:
+        key = self._turn_key(request)
+        if key is None:
+            return await handler(request)
+        recall = self._cached(key)
+        if recall is None:
+            try:
+                resp = await acall_with_budget(lambda: self._search(key[0], key[2]), self.timeout)
+                recall = self._format(resp)
+            except Exception as e:  # noqa: BLE001 - automatic recall fails open
+                recall = self._failed(e)
+            self._remember(key, recall)
+        return await handler(self._with_recall(request, recall))
+
+    # -- optional capture -------------------------------------------------------------------
+
+    def after_agent(self, state: Any, runtime: Any) -> dict[str, Any] | None:
+        if self.capture_turns:
+            self._capture(state, runtime)
+        return None
+
+    async def aafter_agent(self, state: Any, runtime: Any) -> dict[str, Any] | None:
+        if self.capture_turns:
+            self._capture(state, runtime)
+        return None
+
+    def _capture(self, state: Any, runtime: Any) -> None:
+        """Save the user's own message(s) of the turn, once. Assistant replies are never saved:
+        an AI answer must not be learned as a fact about the user."""
+        messages: list[BaseMessage] = list(state.get("messages") or [])
+        last_human = _last_index(messages, HumanMessage)
+        if last_human is None:
+            return
+        first = last_human
+        while first > 0 and isinstance(messages[first - 1], HumanMessage):
+            first -= 1
+        turn = messages[first : last_human + 1]
+        note = "\n\n".join(t for t in (m.text.strip() for m in turn) if t)
+        if not note:
+            return
+        user_id = _user_id(runtime)
+        turn_key = (user_id or "", "captured:" + ",".join(m.id or str(hash(m.text)) for m in turn))
+        with self._lock:
+            if turn_key in self._cache:
+                return
+            self._cache[turn_key] = ""
+        try:
+            client = resolve_client(self.client, self.client_for, user_id)
+        except Exception as e:  # noqa: BLE001 - capture never breaks the run
+            logger.warning("Membase capture skipped: %s", describe_error(e))
+            return
+
+        def save() -> None:
+            try:
+                client.memories.add(note, container=self.container)
+            except Exception as e:  # noqa: BLE001 - logged, the run already finished
+                logger.warning("Membase capture failed: %s", describe_error(e))
+
+        # Saving waits on the network (up to the SDK timeout); do not hold the agent's answer.
+        threading.Thread(target=save, name="membase-capture", daemon=True).start()
+
+    # -- helpers ----------------------------------------------------------------------------
+
+    def _turn_key(self, request: ModelRequest) -> tuple[str, str, str] | None:
+        """(user id, message id, query) of the latest user message, or None when there is none."""
+        messages = list(request.messages or [])
+        idx = _last_index(messages, HumanMessage)
+        if idx is None:
+            return None
+        msg = messages[idx]
+        query = msg.text.strip()
+        if not query:
+            return None
+        return (_user_id(request.runtime) or "", msg.id or f"{idx}:{hash(query)}", query)
+
+    def _search(self, user_id: str, query: str) -> dict[str, Any]:
+        client = resolve_client(self.client, self.client_for, user_id or None)
+        return client.search(query, container=self.container, limit=self.k)
+
+    def _recall(self, fn: Callable[[], dict[str, Any]]) -> str:
+        try:
+            return self._format(call_with_budget(fn, self.timeout))
+        except Exception as e:  # noqa: BLE001 - automatic recall fails open
+            return self._failed(e)
+
+    def _format(self, resp: dict[str, Any]) -> str:
+        failed = unavailable(resp)
+        if failed:
+            logger.warning("Membase recall: some Memories could not answer: %s", "; ".join(failed))
+        return format_passages(resp.get("results") or [])
+
+    def _failed(self, e: BaseException) -> str:
+        logger.warning("Membase recall skipped, continuing without memory: %s", describe_error(e))
+        return ""
+
+    def _cached(self, key: tuple[str, str, str]) -> str | None:
+        with self._lock:
+            return self._cache.get(key[:2])
+
+    def _remember(self, key: tuple[str, str, str], recall: str) -> None:
+        with self._lock:
+            self._cache[key[:2]] = recall
+            self._cache.move_to_end(key[:2])
+            while len(self._cache) > _CACHE_SIZE:
+                self._cache.popitem(last=False)
+
+    def _with_recall(self, request: ModelRequest, recall: str) -> ModelRequest:
+        if not recall:
+            return request
+        block = f"{self.header}\n{recall}"
+        current = request.system_message
+        if current is None:
+            return request.override(system_message=SystemMessage(content=block))
+        if isinstance(current.content, str):
+            content: Any = f"{current.content}\n\n{block}" if current.content else block
+        else:
+            content = [*current.content, {"type": "text", "text": block}]
+        return request.override(system_message=SystemMessage(content=content))
+
+
+def _user_id(runtime: Any) -> str | None:
+    """From the run context (``context_schema`` with ``user_id``), else ``configurable``."""
+    user_id = user_id_from(None, getattr(runtime, "context", None))
+    if user_id is None:
+        try:
+            from langgraph.config import get_config
+
+            user_id = user_id_from(get_config())
+        except Exception:  # noqa: BLE001 - outside a run, or Python 3.10 async
+            user_id = None
+    return user_id
+
+
+def _last_index(messages: list[BaseMessage], kind: type[BaseMessage]) -> int | None:
+    for i in range(len(messages) - 1, -1, -1):
+        if isinstance(messages[i], kind):
+            return i
+    return None

langchain_membase/retrievers.py

@@ -0,0 +1,129 @@
+"""MembaseRetriever: a Membase search as LangChain ``Document``s."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForRetrieverRun,
+    CallbackManagerForRetrieverRun,
+)
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.runnables import RunnableConfig
+from langchain_core.runnables.config import ensure_config, run_in_executor
+from membase.errors import PermissionDeniedError
+from pydantic import Field
+
+from ._common import MembaseClientMixin, logger, unavailable, user_id_from
+
+
+class MembaseUnavailableError(RuntimeError):
+    """A search found nothing *and* some Memories could not answer: not evidence of no memory."""
+
+
+class MembaseRetriever(MembaseClientMixin, BaseRetriever):
+    """Passages from the user's Membase memory, most relevant first.
+
+    Each ``Document`` carries ``container_name`` (the Memory it came from) and ``container``
+    (its id) in ``metadata``, so an answer can cite where it came from.
+
+    Setup:
+        ``pip install langchain-membase`` and set ``MEMBASE_API_KEY`` (Connect > Developer keys
+        in the Membase app), or pass ``client=Membase(...)``.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_membase import MembaseRetriever
+
+            retriever = MembaseRetriever(k=5)
+
+    Usage:
+        .. code-block:: python
+
+            docs = retriever.invoke("what did we decide about the ledger")
+            docs[0].metadata["container_name"]  # "Project decisions"
+
+    Many users:
+        .. code-block:: python
+
+            retriever = MembaseRetriever(client_for=lambda user_id: Membase(api_key=keys[user_id]))
+            retriever.invoke("...", config={"configurable": {"user_id": "alice"}})
+    """
+
+    k: int | None = Field(default=None, ge=1, le=50)
+    """How many passages in all. Unset lets Membase cover every Memory in reach (at least 8)."""
+    container: str | None = None
+    """One container (Memory) id to search; unset searches every Memory the key reaches."""
+
+    def invoke(
+        self, input: str, config: RunnableConfig | None = None, **kwargs: Any
+    ) -> list[Document]:
+        config = ensure_config(config)
+        if kwargs.get("user_id") is None:
+            kwargs["user_id"] = user_id_from(config)
+        return super().invoke(input, config, **kwargs)
+
+    async def ainvoke(
+        self, input: str, config: RunnableConfig | None = None, **kwargs: Any
+    ) -> list[Document]:
+        config = ensure_config(config)
+        if kwargs.get("user_id") is None:
+            kwargs["user_id"] = user_id_from(config)
+        return await super().ainvoke(input, config, **kwargs)
+
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: CallbackManagerForRetrieverRun,
+        k: int | None = None,
+        container: str | None = None,
+        user_id: str | None = None,
+    ) -> list[Document]:
+        client = self._membase(user_id)
+        try:
+            resp = client.search(query, container=container or self.container, limit=k or self.k)
+        except PermissionDeniedError as e:
+            raise PermissionDeniedError(
+                f"{e.message} (this Membase key was narrowed or revoked by its owner; "
+                "do not retry with it)",
+                status=e.status,
+                body=e.body,
+            ) from e
+        docs = [_document(r) for r in resp.get("results") or [] if r.get("content")]
+        failed = unavailable(resp)
+        if failed and not docs:
+            raise MembaseUnavailableError(
+                "no passages came back and these Memories could not answer: " + "; ".join(failed)
+            )
+        if failed:
+            logger.warning("Membase search: some Memories could not answer: %s", "; ".join(failed))
+        return docs
+
+    async def _aget_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: AsyncCallbackManagerForRetrieverRun,
+        k: int | None = None,
+        container: str | None = None,
+        user_id: str | None = None,
+    ) -> list[Document]:
+        # The SDK is synchronous; keep the event loop free while it waits on the network.
+        return await run_in_executor(
+            None,
+            self._get_relevant_documents,
+            query,
+            run_manager=run_manager.get_sync(),
+            k=k,
+            container=container,
+            user_id=user_id,
+        )
+
+
+def _document(r: dict[str, Any]) -> Document:
+    metadata = {key: value for key, value in r.items() if key != "content"}
+    metadata.setdefault("container_name", r.get("container_name") or r.get("container"))
+    return Document(page_content=str(r["content"]), metadata=metadata)

langchain_membase/tools.py

@@ -0,0 +1,296 @@
+"""Agent tools: search, save (only when the user asked) and read the profile."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool, BaseToolkit, ToolException
+from membase import Membase
+from membase.errors import BadRequestError, MembaseError, PermissionDeniedError
+from pydantic import BaseModel, Field
+
+from ._common import (
+    ClientFor,
+    MembaseClientMixin,
+    describe_error,
+    format_passages,
+    format_search,
+    user_id_from,
+)
+
+
+class _MembaseTool(MembaseClientMixin, BaseTool):
+    handle_tool_error: bool = True
+    """A Membase failure becomes the tool's answer, so the model can tell the user."""
+
+    def _client_for_call(self, config: RunnableConfig | None) -> Membase:
+        return self._membase(user_id_from(config))
+
+
+def _container_id(client: Membase, ref: str) -> str:
+    """A container id from a name or id the model gave, or a ToolException naming the choices."""
+    containers = client.containers.list().get("containers") or []
+    for c in containers:
+        if c.get("id") == ref:
+            return ref
+    wanted = ref.strip().casefold()
+    matches = [c for c in containers if str(c.get("name") or "").strip().casefold() == wanted]
+    if len(matches) == 1:
+        return str(matches[0]["id"])
+    names = ", ".join(repr(c.get("name")) for c in containers) or "none"
+    raise ToolException(f"No single Memory called {ref!r} is in reach. Memories in reach: {names}.")
+
+
+class MembaseSearchInput(BaseModel):
+    query: str = Field(description="What to look for, as a natural-language question or topic.")
+    container: str | None = Field(
+        default=None,
+        description="Name of one Memory to search. Omit to search every Memory in reach.",
+    )
+
+
+class MembaseSearchTool(_MembaseTool):
+    """Search the user's Membase memory; each passage names the Memory it came from.
+
+    The tool answers with text for the model and keeps the raw search response as the
+    ``ToolMessage`` artifact.
+    """
+
+    name: str = "membase_search"
+    description: str = (
+        "Search the user's long-term memory (Membase) for passages relevant to a question: what "
+        "they told you before, their projects, decisions, preferences and documents. Each passage "
+        "starts with the name of the Memory it came from in [brackets]; cite it in your answer. "
+        "The first search after a quiet spell can take up to a minute."
+    )
+    args_schema: type[BaseModel] = MembaseSearchInput
+    response_format: Literal["content", "content_and_artifact"] = "content_and_artifact"
+
+    k: int | None = Field(default=None, ge=1, le=50)
+    """How many passages in all; unset lets Membase cover every Memory in reach."""
+    container: str | None = None
+    """Default container id when the model names none; unset searches every Memory."""
+
+    def _run(
+        self,
+        query: str,
+        container: str | None = None,
+        *,
+        config: RunnableConfig,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> tuple[str, dict[str, Any]]:
+        client = self._client_for_call(config)
+        try:
+            target = _container_id(client, container) if container else self.container
+            resp = client.search(query, container=target, limit=self.k)
+        except MembaseError as e:
+            raise ToolException(describe_error(e)) from e
+        return format_search(resp), resp
+
+
+class MembaseSaveInput(BaseModel):
+    content: str = Field(
+        description="The fact or note to keep, in the user's own words. One fact per call."
+    )
+    static: bool = Field(
+        default=False,
+        description=(
+            "True for a lasting fact about the user themself (name, role, a standing "
+            "preference): it goes to their profile. False for a note about anything else."
+        ),
+    )
+    container: str | None = Field(
+        default=None,
+        description="Name of the Memory that should keep a note (ignored when static is true).",
+    )
+
+
+class MembaseSaveTool(_MembaseTool):
+    """Save one fact to the user's Membase memory. Writes only when the model calls it.
+
+    Needs a Read & write key. There is deliberately no delete or forget tool.
+    """
+
+    name: str = "membase_save"
+    description: str = (
+        "Save one fact or note to the user's long-term memory (Membase). Call this ONLY when the "
+        "user asks you to remember something or plainly means for it to be kept; never to log "
+        "the conversation. Pass the content in the user's own words. Set static=true for a "
+        "lasting fact about the user themself; otherwise it is a note kept by one Memory."
+    )
+    args_schema: type[BaseModel] = MembaseSaveInput
+
+    container: str | None = None
+    """Container id that keeps notes when the model names none. Needed when the key reaches
+    several Memories (unless the model names one)."""
+
+    def _run(
+        self,
+        content: str,
+        static: bool = False,
+        container: str | None = None,
+        *,
+        config: RunnableConfig,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        client = self._client_for_call(config)
+        try:
+            target = None
+            if not static:
+                target = _container_id(client, container) if container else self.container
+            resp = client.memories.add(content, container=target, static=static)
+        except BadRequestError as e:
+            if not static and target is None:
+                raise ToolException(_which_container(client, e)) from e
+            raise ToolException(describe_error(e)) from e
+        except MembaseError as e:
+            raise ToolException(describe_error(e)) from e
+        return _saved(resp or {})
+
+
+def _which_container(client: Membase, e: BadRequestError) -> str:
+    try:
+        names = [c.get("name") for c in client.containers.list().get("containers") or []]
+    except MembaseError:
+        names = []
+    listed = ", ".join(repr(n) for n in names) or "unknown"
+    return (
+        f"{e.message}. Several Memories are in reach; call again with container set to one "
+        f"of: {listed}."
+    )
+
+
+def _saved(resp: dict[str, Any]) -> str:
+    if resp.get("static"):
+        return "Recorded in the user's profile."
+    if resp.get("status") == "learned":
+        return "Saved and learned; a search can find it now."
+    where = resp.get("container_name") or resp.get("container") or "the Memory"
+    return (
+        f"Saved to {where}. It is learned in the background, so a search may not find it until "
+        "that finishes."
+    )
+
+
+class MembaseProfileInput(BaseModel):
+    topic: str | None = Field(
+        default=None,
+        description="Optional current topic, to also get the profile passages relevant to it.",
+    )
+
+
+class MembaseProfileTool(_MembaseTool):
+    """Who the user is: standing facts and recently changed ones, from the Membase profile.
+
+    Only works when the key's owner ticked the profile for it; otherwise Membase answers 403.
+    """
+
+    name: str = "membase_profile"
+    description: str = (
+        "Read who the user is from their Membase profile: standing facts (name, role, lasting "
+        "preferences) and recently changed facts. Call it once near the start of a conversation, "
+        "optionally with the current topic."
+    )
+    args_schema: type[BaseModel] = MembaseProfileInput
+
+    def _run(
+        self,
+        topic: str | None = None,
+        *,
+        config: RunnableConfig,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        client = self._client_for_call(config)
+        try:
+            resp = client.profile(q=topic or None)
+        except PermissionDeniedError as e:
+            raise ToolException(
+                describe_error(e) + " (A key reads the profile only if its owner ticked it.)"
+            ) from e
+        except MembaseError as e:
+            raise ToolException(describe_error(e)) from e
+        return _format_profile(resp or {})
+
+
+def _text(item: Any) -> str:
+    if isinstance(item, str):
+        return item.strip()
+    if isinstance(item, dict):
+        return str(item.get("content") or item.get("description") or item.get("text") or "").strip()
+    return str(item).strip()
+
+
+def _format_profile(resp: dict[str, Any]) -> str:
+    parts = []
+    static = [t for t in map(_text, resp.get("static") or []) if t]
+    dynamic = [t for t in map(_text, resp.get("dynamic") or []) if t]
+    if static:
+        parts.append("Standing facts:\n" + "\n".join(f"- {t}" for t in static))
+    if dynamic:
+        parts.append("Recently changed:\n" + "\n".join(f"- {t}" for t in dynamic))
+    if resp.get("results"):
+        passages = format_passages(resp["results"])
+        if passages:
+            parts.append("Relevant to the topic:\n" + passages)
+    return "\n\n".join(parts) or "The profile is empty."
+
+
+class MembaseToolkit(MembaseClientMixin, BaseToolkit):
+    """The Membase tools, sharing one client (or one ``client_for``).
+
+    .. code-block:: python
+
+        from langchain_membase import MembaseToolkit
+
+        tools = MembaseToolkit().get_tools()  # MEMBASE_API_KEY from the environment
+    """
+
+    container: str | None = None
+    """Default container id for search and save when the model names none."""
+    k: int | None = Field(default=None, ge=1, le=50)
+    """How many passages a search returns in all."""
+    save: bool = True
+    """Include ``membase_save`` (a Read key cannot write anyway)."""
+    profile: bool = True
+    """Include ``membase_profile`` (only useful if the key's owner ticked the profile)."""
+
+    def get_tools(self) -> list[BaseTool]:
+        shared: dict[str, Any] = {"client": self.client, "client_for": self.client_for}
+        tools: list[BaseTool] = [MembaseSearchTool(**shared, container=self.container, k=self.k)]
+        if self.save:
+            tools.append(MembaseSaveTool(**shared, container=self.container))
+        if self.profile:
+            tools.append(MembaseProfileTool(**shared))
+        return tools
+
+
+def membase_tools(
+    client: Membase | None = None,
+    *,
+    client_for: ClientFor | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    local: str | os.PathLike | bool | None = None,
+    container: str | None = None,
+    k: int | None = None,
+    save: bool = True,
+    profile: bool = True,
+) -> list[BaseTool]:
+    """``MembaseToolkit(...).get_tools()``: search, save and profile sharing one client.
+
+    ``save=False`` leaves the write tool out; ``profile=False`` leaves the profile out.
+    """
+    return MembaseToolkit(
+        client=client,
+        client_for=client_for,
+        api_key=api_key,
+        base_url=base_url,
+        local=os.fspath(local) if isinstance(local, os.PathLike) else local,
+        container=container,
+        k=k,
+        save=save,
+        profile=profile,
+    ).get_tools()

langchain_membase-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: langchain-membase
+Version: 0.1.0
+Summary: Membase long-term memory for LangChain and LangGraph: a retriever, agent tools and a recall middleware.
+Project-URL: Homepage, https://membase.com
+Project-URL: Documentation, https://github.com/unibaseio/membase/tree/main/integrations/langchain#readme
+Project-URL: Repository, https://github.com/unibaseio/membase
+Project-URL: Issues, https://github.com/unibaseio/membase/issues
+Author: Unibase
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langchain,langgraph,membase,memory,retriever
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: unibaseio-membase>=0.3.2
+Provides-Extra: agents
+Requires-Dist: langchain<2,>=1.1; extra == 'agents'
+Description-Content-Type: text/markdown
+
+# langchain-membase
+
+[Membase](https://membase.com) long-term memory for LangChain and LangGraph (Python).
+
+Membase keeps a person's memory in their own account: named **Memories** (containers) that
+learn from their notes, files and conversations, plus a **profile** of standing facts. This
+package gives a LangChain app three ways to use it:
+
+| Piece | LangChain type | What it does |
+|---|---|---|
+| `MembaseRetriever` | `BaseRetriever` | a Membase search as `Document`s, each citing its Memory in `metadata["container_name"]` |
+| `MembaseToolkit` (`membase_tools()`): `MembaseSearchTool`, `MembaseSaveTool`, `MembaseProfileTool` | `BaseToolkit` / `BaseTool` | agent tools: search, save (only when the user asks), read the profile |
+| `MembaseRecallMiddleware` | LangChain v1 `AgentMiddleware` | time-boxed recall added to the system message before the model call of a `create_agent` agent |
+
+There is deliberately **no delete or forget tool**, and the package never confirms a
+destructive action. It also does not implement LangGraph's `BaseStore`: Membase is a memory
+that learns, not a key-value store (there is no get-by-key), so it is offered as retrieval and
+tools instead.
+
+## Install
+
+```bash
+pip install langchain-membase             # retriever + tools (needs langchain-core)
+pip install 'langchain-membase[agents]'   # + the create_agent middleware (needs langchain>=1.1)
+```
+
+Python 3.10+. Get a key in the Membase app under **Connect › Developer keys** and set it:
+
+```bash
+export MEMBASE_API_KEY=mbk_...
+```
+
+A **Read** key can search and read the profile (if its owner ticked it); saving needs a
+**Read & write** key. One key is one person's account.
+
+## Retriever
+
+```python
+from langchain_membase import MembaseRetriever
+
+retriever = MembaseRetriever(k=5)                     # MEMBASE_API_KEY from the environment
+docs = retriever.invoke("what did we decide about the ledger")
+for d in docs:
+    print(d.metadata["container_name"], "·", d.page_content)
+```
+
+* `k` (1–50) is the number of passages in all; unset lets Membase cover every Memory in reach.
+* `container="mv-…"` limits the search to one Memory (its id from `client.containers.list()`).
+  Both can also be passed per call: `retriever.invoke(q, k=3, container="mv-…")`.
+* If no passage comes back **and** some Memory could not answer (no model, dormant), the
+  retriever raises `MembaseUnavailableError` instead of returning `[]`: that is not evidence of
+  "no memory". When some Memories answered, it returns their passages and logs the rest.
+* A `403` (`membase.PermissionDeniedError`) means the key's owner narrowed or revoked it; do
+  not retry with that key.
+
+It works anywhere a retriever does, e.g. in an LCEL chain:
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnablePassthrough
+
+def cite(docs):
+    return "\n".join(f"[{d.metadata['container_name']}] {d.page_content}" for d in docs)
+
+prompt = ChatPromptTemplate.from_template("Memory:\n{memory}\n\nQuestion: {question}")
+chain = {"memory": retriever | cite, "question": RunnablePassthrough()} | prompt | llm
+```
+
+## Agent tools
+
+```python
+from langchain.agents import create_agent
+from langchain_membase import MembaseToolkit
+
+agent = create_agent("openai:gpt-5", tools=MembaseToolkit().get_tools())   # or membase_tools()
+agent.invoke({"messages": [{"role": "user", "content": "What did we pick for the ledger?"}]})
+```
+
+| Tool | Arguments | Notes |
+|---|---|---|
+| `membase_search` | `query`, optional `container` (a Memory's **name**) | passages as `- [Memory name] text`; the raw response is the `ToolMessage` artifact; Memories that could not answer are reported |
+| `membase_save` | `content` (the user's words), `static`, optional `container` | the description tells the model to save **only when the user asks**; `static=true` records a standing fact in the profile; with several Memories in reach it needs a `container` (or a default `container=` id on the tool) and says which names exist |
+| `membase_profile` | optional `topic` | standing and recently changed facts; only for a key whose owner ticked the profile |
+
+`MembaseToolkit(save=False, profile=False)` (or `membase_tools(client, save=False, profile=False)`) leaves tools out; `container=` and `k=` set
+defaults. Errors come back as the tool's answer (`handle_tool_error=True`), so the model can
+tell the user, e.g. "this Membase key was narrowed or revoked".
+
+Explicit tool calls use the SDK's own timeout (90 s): the first search after a quiet spell
+takes longer while the user's memory wakes.
+
+## Recall middleware (LangChain v1)
+
+```python
+from langchain.agents import create_agent
+from langchain_membase import MembaseRecallMiddleware, membase_tools
+
+agent = create_agent(
+    "openai:gpt-5",
+    tools=membase_tools(),
+    system_prompt="You are a helpful assistant.",
+    middleware=[MembaseRecallMiddleware(k=5, timeout=8.0)],
+)
+```
+
+Before the model call, the middleware searches Membase for the latest user message and appends
+the passages (each with its Memory) to the system message of that request.
+
+* **Time-boxed and fail-open**: it waits at most `timeout` seconds (8 by default). On a timeout,
+  a `403` or any other error it logs a warning on the `langchain_membase` logger and the model
+  runs without memory. A search that ran past the budget finishes in the background, which
+  wakes the memory for the next turn.
+* **Once per user message**: model calls that follow tool calls in the same turn reuse the
+  result.
+* **Nothing is persisted**: the recall lives in the model request only, never in the agent's
+  state or checkpoint.
+* **No automatic writes by default**. `capture_turns=True` (opt-in) saves the user's own
+  message(s) of each turn, once, as a note in `container=`, in the background. Assistant
+  replies are never saved, so an AI answer is not learned as a fact about the user.
+
+## Many users
+
+A Membase key belongs to one person, so a multi-user app holds one key (or one local
+directory) **per end user** and passes `client_for`, a function from user id to that user's
+client. Every class and `membase_tools()` accept it. The user id is read from the run:
+
+```python
+from functools import lru_cache
+from membase import Membase
+from langchain_membase import MembaseRecallMiddleware, MembaseRetriever, membase_tools
+
+@lru_cache(maxsize=1024)            # reuse each user's client (and its connection pool)
+def client_for(user_id: str) -> Membase:
+    return Membase(api_key=load_user_key(user_id))   # that user's key, never another's
+
+retriever = MembaseRetriever(client_for=client_for)
+retriever.invoke("...", config={"configurable": {"user_id": "alice"}})
+
+agent = create_agent(
+    model,
+    tools=membase_tools(client_for=client_for),
+    middleware=[MembaseRecallMiddleware(client_for=client_for)],
+)
+agent.invoke({"messages": [...]}, config={"configurable": {"user_id": "alice"}})
+```
+
+The user id is taken from `config["configurable"]["user_id"]`, or from a LangGraph run
+context with a `user_id` field (`create_agent(..., context_schema=Ctx)` and
+`agent.invoke(..., context=Ctx(user_id="alice"))`). With `client_for` set, a call that carries
+no user id raises `MissingUserIdError` (the middleware logs it and skips recall); it never
+falls back to another client. `client_for` and `client`/`api_key`/`local` are mutually
+exclusive.
+
+**Without `client_for`, one client serves every call.** That suits a personal agent (your own
+key, your own memory), not a multi-user app.
+
+Local mode keeps each person in their own directory:
+`client_for=lambda uid: Membase(local=f"/data/membase/{uid}")`
+(`pip install 'unibaseio-membase[local]'`, Python 3.12+, and an LLM key such as
+`OPENAI_API_KEY`).
+
+## Configuration
+
+Every class takes `client=Membase(...)`, or `api_key=` / `base_url=` / `local=`; otherwise
+`MEMBASE_API_KEY` and `MEMBASE_BASE_URL` come from the environment. The API host defaults to
+`https://api.app.membase.com`.
+
+## Development
+
+```bash
+uv venv .venv && uv pip install --python .venv/bin/python -e . \
+  'langchain>=1.1' langgraph langchain-tests pytest pytest-asyncio ruff
+.venv/bin/python -m pytest              # offline: the real SDK over httpx.MockTransport
+MEMBASE_API_KEY=mbk_... .venv/bin/python examples/live_smoke.py   # against the real API
+uv build
+```
+
+The offline suite includes LangChain's standard tests (`langchain-tests`) for the retriever
+and the three tools, and runs the tools and the middleware inside a real `create_agent`
+(LangGraph) graph with a scripted chat model.
+
+## Licence
+
+MIT

langchain_membase-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+langchain_membase/__init__.py,sha256=RcFEEfKDkPjThqeQ6k3w0DTG739KJ3BuHg7etOkWtsY,1349
+langchain_membase/_common.py,sha256=nWphcafsGFULz9gPepxd2iGQUlmTNTIM-9pYH5J3fhY,9530
+langchain_membase/middleware.py,sha256=gFpnF18k3ZT9Nc6e0kDtwgUQpSFpdhBCVDlO6MBVhyo,9946
+langchain_membase/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_membase/retrievers.py,sha256=_O27S1Z8cND7BHzOcqoa1Yc2SQAT4IO7QXs90NIHHc8,4784
+langchain_membase/tools.py,sha256=xxX_-Ww_ZxjUZxBLDkAPgdHgL6-1-Ju4OX82lAjMTjk,11036
+langchain_membase-0.1.0.dist-info/METADATA,sha256=fKh7QfxWmK51LDpRSalonF55iPohBl5ZmcK8t5Q-e5A,9741
+langchain_membase-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+langchain_membase-0.1.0.dist-info/licenses/LICENSE,sha256=SWhYL0rjdALC-gYSOEAX-Z4LpxatwZx1kP6XwuOTSzs,1064
+langchain_membase-0.1.0.dist-info/RECORD,,

langchain_membase-0.1.0.dist-info/WHEEL

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

langchain_membase-0.1.0.dist-info/licenses/LICENSE

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