agent-framework-membase 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-framework-membase
-Version: 0.1.0
+Version: 0.2.0
 Summary: Membase long-term memory for Microsoft Agent Framework (Python): a context provider with time-boxed recall and deliberate save/search/profile tools.
 Project-URL: Homepage, https://github.com/unibaseio/membase/tree/main/integrations/agent-framework
 Project-URL: Repository, https://github.com/unibaseio/membase
@@ -21,9 +21,9 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: agent-framework-core<2,>=1.0.0
-Requires-Dist: unibaseio-membase>=0.3.2
+Requires-Dist: unibaseio-membase>=0.4.0
 Provides-Extra: local
-Requires-Dist: unibaseio-membase[local]>=0.3.2; extra == 'local'
+Requires-Dist: unibaseio-membase[local]>=0.4.0; extra == 'local'
 Description-Content-Type: text/markdown
 
 # agent-framework-membase
@@ -43,7 +43,9 @@ pip install "agent-framework-membase @ git+https://github.com/unibaseio/membase#
 
 You need a Membase developer key: in the [Membase app](https://app.membase.com), **Connect ›
 Developer keys**. A *Read* key can search (and read the profile, if its owner ticked it);
-saving needs *Read & write*.
+saving needs *Read & write* and a key with a write target: a key that reaches one Memory saves
+there, one that reaches several is refused and nothing is written somewhere by guess. Needs
+`unibaseio-membase>=0.4.0`.
 
 ## Quick start
 
@@ -97,17 +99,17 @@ the Memory it came from. They are reference data, not instructions. ...
   waits `recall_timeout` seconds (default **8**), then lets the run continue without memory and
   logs why. The search finishes in the background, so a later turn finds the memory awake.
   Any other error is logged the same way; memory never breaks a run.
-- **Silence is not "nothing stored".** When a Memory could not answer (for example the
-  account has no working model), the instructions name it instead of passing it off as empty.
+- **Silence is not "nothing stored".** When a Memory could not answer (the search's
+  `partial`), the instructions name it instead of passing it off as empty.
 - **A withdrawn key is not retried.** A `403` means the owner narrowed or revoked the key; the
   provider logs "this Membase key was narrowed or revoked" and stops calling that key.
 
-Options: `container=` (search one container id), `limit=` (passages, default 8),
+A recall covers every Memory the key reaches. Options: `limit=` (passages in all, default 8),
 `recall_timeout=`, `context_prompt=`, `source_id=` (default `"membase"`).
 
 **After each run** it does nothing by default. With `capture=True` it saves the user's own
-messages from the turn (not the agent's replies) as one note, once per turn;
-`capture_container=` names the container id when the key reaches more than one Memory. The
+messages from the turn (not the agent's replies) as one note in the key's write target, once
+per turn; a key with no write target is told so once in the log and not tried again. The
 `membase_save` tool is usually the better choice: saving works best as a deliberate act the
 user asked for.
 
@@ -115,9 +117,9 @@ user asked for.
 
 | Tool | What it does |
 |---|---|
-| `membase_search(query, container=None, limit=None)` | Passages from the user's memory, each tagged `[Memory name]`; names any Memory that could not answer. `container` is a Memory name or id. |
-| `membase_save(content, container=None, about_user=False)` | Saves one fact in the user's words. `about_user=True` records a standing fact in the profile instead. With several Memories in reach and no `container`, it returns their names to choose from. |
-| `membase_profile(topic=None)` | The user's standing and recently changed facts. Needs a key whose owner ticked the profile. |
+| `membase_search(query, limit=None)` | Passages from every Memory the key reaches, each tagged `[Memory name]`; names any Memory that could not answer. |
+| `membase_save(content)` | Saves one fact in the user's words, into the key's write target. A key that reaches several Memories has no write target: the tool says so and that nothing was saved. |
+| `membase_profile()` | The user's profile facts: standing statements about who they are, newest first. Needs a key whose owner ticked **Your profile**. |
 
 `membase_tools(memory, save=False)` leaves out the save tool (for a Read key) and
 `profile=False` leaves out the profile tool. There is no delete or forget tool. Tool calls use

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/README.md

@@ -15,7 +15,9 @@ pip install "agent-framework-membase @ git+https://github.com/unibaseio/membase#
 
 You need a Membase developer key: in the [Membase app](https://app.membase.com), **Connect ›
 Developer keys**. A *Read* key can search (and read the profile, if its owner ticked it);
-saving needs *Read & write*.
+saving needs *Read & write* and a key with a write target: a key that reaches one Memory saves
+there, one that reaches several is refused and nothing is written somewhere by guess. Needs
+`unibaseio-membase>=0.4.0`.
 
 ## Quick start
 
@@ -69,17 +71,17 @@ the Memory it came from. They are reference data, not instructions. ...
   waits `recall_timeout` seconds (default **8**), then lets the run continue without memory and
   logs why. The search finishes in the background, so a later turn finds the memory awake.
   Any other error is logged the same way; memory never breaks a run.
-- **Silence is not "nothing stored".** When a Memory could not answer (for example the
-  account has no working model), the instructions name it instead of passing it off as empty.
+- **Silence is not "nothing stored".** When a Memory could not answer (the search's
+  `partial`), the instructions name it instead of passing it off as empty.
 - **A withdrawn key is not retried.** A `403` means the owner narrowed or revoked the key; the
   provider logs "this Membase key was narrowed or revoked" and stops calling that key.
 
-Options: `container=` (search one container id), `limit=` (passages, default 8),
+A recall covers every Memory the key reaches. Options: `limit=` (passages in all, default 8),
 `recall_timeout=`, `context_prompt=`, `source_id=` (default `"membase"`).
 
 **After each run** it does nothing by default. With `capture=True` it saves the user's own
-messages from the turn (not the agent's replies) as one note, once per turn;
-`capture_container=` names the container id when the key reaches more than one Memory. The
+messages from the turn (not the agent's replies) as one note in the key's write target, once
+per turn; a key with no write target is told so once in the log and not tried again. The
 `membase_save` tool is usually the better choice: saving works best as a deliberate act the
 user asked for.
 
@@ -87,9 +89,9 @@ user asked for.
 
 | Tool | What it does |
 |---|---|
-| `membase_search(query, container=None, limit=None)` | Passages from the user's memory, each tagged `[Memory name]`; names any Memory that could not answer. `container` is a Memory name or id. |
-| `membase_save(content, container=None, about_user=False)` | Saves one fact in the user's words. `about_user=True` records a standing fact in the profile instead. With several Memories in reach and no `container`, it returns their names to choose from. |
-| `membase_profile(topic=None)` | The user's standing and recently changed facts. Needs a key whose owner ticked the profile. |
+| `membase_search(query, limit=None)` | Passages from every Memory the key reaches, each tagged `[Memory name]`; names any Memory that could not answer. |
+| `membase_save(content)` | Saves one fact in the user's words, into the key's write target. A key that reaches several Memories has no write target: the tool says so and that nothing was saved. |
+| `membase_profile()` | The user's profile facts: standing statements about who they are, newest first. Needs a key whose owner ticked **Your profile**. |
 
 `membase_tools(memory, save=False)` leaves out the save tool (for a Read key) and
 `profile=False` leaves out the profile tool. There is no delete or forget tool. Tool calls use

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/examples/live_smoke.py

@@ -5,7 +5,7 @@
 A real ``agent_framework.Agent`` runs with the Membase context provider and tools attached;
 its chat client is a stand-in that calls the tools the way a model would and prints what the
 model would have seen. Writes nothing unless MEMBASE_SMOKE_WRITE=1 (then it saves one note to
-MEMBASE_SMOKE_CONTAINER, a container id or name). Exits 0 without a key.
+the key's write target: a Read & write key that reaches one Memory). Exits 0 without a key.
 """
 
 from __future__ import annotations
@@ -57,7 +57,7 @@ async def main() -> int:
     # MEMBASE_API_KEY from the environment; the host is the package's default unless MEMBASE_BASE_URL is set.
     client = Membase(base_url=os.environ.get("MEMBASE_BASE_URL") or DEFAULT_BASE_URL)
 
-    print("containers:", [c.get("name") for c in client.containers.list().get("containers", [])])
+    print("Memories in reach:", [m.get("name") for m in client.capabilities().get("memories") or []])
 
     calls: list[tuple[str, dict[str, Any]]] = [("membase_search", {"query": question, "limit": 5})]
     if os.environ.get("MEMBASE_SMOKE_PROFILE") == "1":
@@ -66,10 +66,7 @@ async def main() -> int:
         calls.append(
             (
                 "membase_save",
-                {
-                    "content": f"Smoke test note from agent-framework-membase at {time.ctime()}.",
-                    "container": os.environ.get("MEMBASE_SMOKE_CONTAINER"),
-                },
+                {"content": f"Smoke test note from agent-framework-membase at {time.ctime()}."},
             )
         )
     model = StandInModel(calls)

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/pyproject.toml

@@ -25,11 +25,11 @@ classifiers = [
 ]
 dependencies = [
     "agent-framework-core>=1.0.0,<2",
-    "unibaseio-membase>=0.3.2",
+    "unibaseio-membase>=0.4.0",
 ]
 
 [project.optional-dependencies]
-local = ["unibaseio-membase[local]>=0.3.2"]
+local = ["unibaseio-membase[local]>=0.4.0"]
 
 [project.urls]
 Homepage = "https://github.com/unibaseio/membase/tree/main/integrations/agent-framework"

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/src/agent_framework_membase/_common.py

@@ -17,6 +17,7 @@ from membase.errors import (
     PermissionDeniedError,
     RateLimitError,
     UnprocessableEntityError,
+    WriteTargetRequiredError,
 )
 
 logger = logging.getLogger("agent_framework_membase")
@@ -35,6 +36,11 @@ ClientFor = Callable[[str], Membase]
 
 REVOKED = "this Membase key was narrowed or revoked by its owner, or it does not allow this operation"
 
+NO_WRITE_TARGET = (
+    "this Membase key reaches several Memories and has no write target, so nothing was saved; "
+    "give the key a single Memory under Connect › Developer keys in the Membase app"
+)
+
 
 def bind_user(session: Any, user_id: str, *, source_id: str = DEFAULT_SOURCE_ID) -> None:
     """Record which person a session belongs to, for ``client_for``.
@@ -140,6 +146,8 @@ def _log_late_failure(task: asyncio.Future[Any]) -> None:
 
 def describe_error(exc: BaseException) -> str:
     """One actionable sentence for an SDK failure."""
+    if isinstance(exc, WriteTargetRequiredError):
+        return f"Membase did not save it: {NO_WRITE_TARGET}."
     if isinstance(exc, PermissionDeniedError):
         return f"Membase refused the call (403): {REVOKED}. Do not retry with this key. ({exc.message})"
     if isinstance(exc, APITimeoutError):
@@ -158,21 +166,26 @@ def describe_error(exc: BaseException) -> str:
 
 
 def format_search(answer: Mapping[str, Any] | None) -> tuple[list[str], list[str]]:
-    """``(passages, unanswered)``: one line per passage citing its container, one per Memory
-    that could not answer (so an empty result is never mistaken for an empty memory)."""
+    """``(passages, unanswered)``: one line per passage citing its Memory, one per Memory that
+    could not answer or whose passages did not fit the limit (``partial``), so an empty result
+    is never mistaken for an empty memory."""
     answer = answer or {}
     passages: list[str] = []
-    for hit in answer.get("results") or []:
+    for hit in answer.get("items") or []:
         if not isinstance(hit, Mapping):
             continue
         content = str(hit.get("content") or "").strip()
         if not content:
             continue
-        where = str(hit.get("container_name") or hit.get("container") or "Membase").strip()
+        where = str(hit.get("memory_name") or "Membase").strip()
         passages.append(f"- [{where}] {content}")
     unanswered: list[str] = []
-    for c in answer.get("containers") or []:
-        if isinstance(c, Mapping) and c.get("error"):
-            name = c.get("name") or c.get("id") or "a Memory"
-            unanswered.append(f'- "{name}" could not answer: {c["error"]}')
+    for p in answer.get("partial") or []:
+        if not isinstance(p, Mapping):
+            continue
+        name = p.get("memory_name") or "a Memory"
+        if p.get("reason") == "truncated":
+            unanswered.append(f'- "{name}" had more passages than the limit let through')
+        else:
+            unanswered.append(f'- "{name}" could not answer')
     return passages, unanswered

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/src/agent_framework_membase/_provider.py

@@ -9,10 +9,11 @@ from typing import TYPE_CHECKING, Any
 
 from agent_framework import AgentSession, ContextProvider, SessionContext
 from membase import Membase
-from membase.errors import BadRequestError, PermissionDeniedError
+from membase.errors import PermissionDeniedError, WriteTargetRequiredError
 
 from ._common import (
     DEFAULT_SOURCE_ID,
+    NO_WRITE_TARGET,
     REVOKED,
     ClientFor,
     Clients,
@@ -59,12 +60,12 @@ class MembaseContextProvider(ContextProvider):
     ``recall_timeout`` seconds (8 by default: the first search after a quiet spell can take
     up to a minute while the memory wakes). On a timeout or any error the run continues
     without memory and the reason is logged. Passages are added to the run's instructions,
-    each citing the Memory (container) it came from; a Memory that could not answer is named
-    too, so the model does not read silence as "nothing stored".
+    each citing the Memory it came from; a Memory that could not answer is named too, so the
+    model does not read silence as "nothing stored".
 
     ``after_run`` saves nothing unless ``capture=True``. With capture on, the user's own
-    messages from the turn (not the agent's replies) are added as one note; prefer the
-    deliberate ``membase_save`` tool from :func:`membase_tools`.
+    messages from the turn (not the agent's replies) are added as one note in the key's write
+    target; prefer the deliberate ``membase_save`` tool from :func:`membase_tools`.
 
     One client serves every session unless ``client_for`` is given: then each session must
     name its person with :func:`bind_user` and is served by ``client_for(user_id)``, that
@@ -84,12 +85,10 @@ class MembaseContextProvider(ContextProvider):
         local: str | os.PathLike[str] | bool | None = None,
         client_for: ClientFor | None = None,
         source_id: str = DEFAULT_SOURCE_ID,
-        container: str | None = None,
         limit: int | None = DEFAULT_LIMIT,
         recall_timeout: float = DEFAULT_RECALL_TIMEOUT,
         context_prompt: str = DEFAULT_CONTEXT_PROMPT,
         capture: bool = False,
-        capture_container: str | None = None,
         capture_title: str = "Agent Framework conversation",
     ) -> None:
         """Create the provider.
@@ -103,14 +102,13 @@ class MembaseContextProvider(ContextProvider):
             client_for: ``user_id -> Membase`` for an app serving several people; the user id
                 comes from :func:`bind_user` on the session. Excludes the arguments above.
             source_id: The provider id; also the ``session.state`` key of the user binding.
-            container: Search only this container id; default every Memory the key reaches.
-            limit: Passages per recall (``None`` lets the server cover every Memory in reach).
+            limit: Passages per recall, across every Memory the key reaches (``None``: the
+                server's default).
             recall_timeout: Seconds the automatic recall may take before the run goes on
                 without it.
             context_prompt: Heading placed above the recalled passages.
-            capture: Save the user's messages after each turn. Off by default.
-            capture_container: Container id that receives captured turns; required when the
-                key reaches more than one Memory.
+            capture: Save the user's messages after each turn, into the key's write target.
+                Off by default.
             capture_title: Title of captured notes.
         """
         super().__init__(source_id)
@@ -122,12 +120,10 @@ class MembaseContextProvider(ContextProvider):
             client_for=client_for,
             source_id=source_id,
         )
-        self.container = container
         self.limit = limit
         self.recall_timeout = recall_timeout
         self.context_prompt = context_prompt
         self.capture = capture
-        self.capture_container = capture_container
         self.capture_title = capture_title
         # A 403 means the owner narrowed or revoked the key: stop calling it automatically.
         self._refused_recall: weakref.WeakSet[Membase] = weakref.WeakSet()
@@ -176,7 +172,6 @@ class MembaseContextProvider(ContextProvider):
             answer = await in_thread(
                 client.search,
                 texts[-1],
-                container=self.container,
                 limit=self.limit,
                 timeout=self.recall_timeout,
             )
@@ -205,8 +200,8 @@ class MembaseContextProvider(ContextProvider):
             parts.append("<membase_memory>\n" + "\n".join(passages) + "\n</membase_memory>")
         if unanswered:
             parts.append(
-                "These Memories could not answer this time, so a missing passage from them is "
-                "not evidence that nothing is stored:\n" + "\n".join(unanswered)
+                "These Memories did not fully answer this time, so a missing passage from them "
+                "is not evidence that nothing is stored:\n" + "\n".join(unanswered)
             )
         context.extend_instructions(self.source_id, "\n\n".join(parts))
 
@@ -231,7 +226,6 @@ class MembaseContextProvider(ContextProvider):
             await in_thread(
                 client.memories.add,
                 "\n\n".join(texts),
-                container=self.capture_container,
                 title=self.capture_title,
                 timeout=self.recall_timeout,
             )
@@ -247,13 +241,9 @@ class MembaseContextProvider(ContextProvider):
                 REVOKED,
                 exc.message,
             )
-        except BadRequestError as exc:
-            hint = (
-                ""
-                if self.capture_container
-                else " (set capture_container= when the key reaches several Memories)"
-            )
-            logger.warning("Membase: capture refused: %s%s", exc.message, hint)
+        except WriteTargetRequiredError:
+            self._refused_capture.add(client)
+            logger.error("Membase: capture stopped: %s.", NO_WRITE_TARGET)
         except Exception as exc:  # noqa: BLE001 - a failed capture must never break a run
             logger.warning("Membase: capture failed: %s", describe_error(exc))
 

agent_framework_membase-0.2.0/src/agent_framework_membase/_tools.py

@@ -0,0 +1,142 @@
+"""``membase_tools``: search, save and profile as Agent Framework function tools."""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated
+
+from agent_framework import FunctionInvocationContext, FunctionTool, tool
+from membase import Membase
+from membase.errors import PermissionDeniedError, WriteTargetRequiredError
+from pydantic import Field
+
+from ._common import (
+    DEFAULT_SOURCE_ID,
+    NO_WRITE_TARGET,
+    REVOKED,
+    ClientFor,
+    Clients,
+    NoUserBound,
+    describe_error,
+    format_search,
+    in_thread,
+)
+
+
+def membase_tools(
+    client: Membase | None = None,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    local: str | os.PathLike[str] | bool | None = None,
+    client_for: ClientFor | None = None,
+    source_id: str = DEFAULT_SOURCE_ID,
+    save: bool = True,
+    profile: bool = True,
+) -> list[FunctionTool]:
+    """Membase as Agent Framework function tools: ``membase_search``, ``membase_save``,
+    ``membase_profile``.
+
+    Pass a ready ``Membase`` client, or ``api_key`` / ``base_url`` / ``local``, or
+    ``client_for`` (``user_id -> Membase``) with the user bound to each session by
+    :func:`bind_user` (the same binding :class:`MembaseContextProvider` reads). Tool calls use
+    the SDK's own timeout (90 s by default), since the model asked for them explicitly.
+
+    ``save=False`` leaves out ``membase_save`` (for a Read key); ``profile=False`` leaves out
+    ``membase_profile`` (for a key whose owner did not share the profile). There is no delete
+    or forget tool.
+    """
+    clients = Clients(
+        client, api_key=api_key, base_url=base_url, local=local, client_for=client_for, source_id=source_id
+    )
+
+    def _client(ctx: FunctionInvocationContext | None) -> Membase:
+        return clients.for_session(ctx.session if ctx is not None else None)
+
+    @tool(name="membase_search", approval_mode="never_require")
+    async def membase_search(
+        query: Annotated[str, Field(description="What to look for, in natural language.")],
+        limit: Annotated[int | None, Field(description="How many passages, 1-50.", ge=1, le=50)] = None,
+        ctx: FunctionInvocationContext | None = None,
+    ) -> str:
+        """Search the user's long-term Membase memory (every Memory the key reaches). Returns
+        passages, each tagged with the Memory it came from; name that Memory when you use a
+        passage."""
+        try:
+            mb = _client(ctx)
+            answer = await in_thread(mb.search, query, limit=limit)
+        except NoUserBound as exc:
+            return f"Membase is not available: {exc}."
+        except Exception as exc:  # noqa: BLE001 - the tool answers the model with the error
+            return describe_error(exc)
+        passages, unanswered = format_search(answer)
+        out = (
+            ["Passages from the user's Membase memory:", *passages]
+            if passages
+            else ["No passages in the user's Membase memory matched."]
+        )
+        if unanswered:
+            out += [
+                "Some Memories did not fully answer, so this is not proof nothing is stored:",
+                *unanswered,
+            ]
+        return "\n".join(out)
+
+    @tool(name="membase_save", approval_mode="never_require")
+    async def membase_save(
+        content: Annotated[
+            str, Field(description="The fact to keep, in the user's own words. One fact per call.")
+        ],
+        ctx: FunctionInvocationContext | None = None,
+    ) -> str:
+        """Save something to the user's Membase memory. Call this only when the user asks you
+        to remember something or plainly means it; never save your own conclusions."""
+        try:
+            mb = _client(ctx)
+            result = await in_thread(mb.memories.add, content)
+        except NoUserBound as exc:
+            return f"Membase is not available: {exc}."
+        except WriteTargetRequiredError:
+            return f"Membase did not save it: {NO_WRITE_TARGET}."
+        except PermissionDeniedError as exc:
+            return f"Membase did not save it (403): {REVOKED}; a Read key cannot write. ({exc.message})"
+        except Exception as exc:  # noqa: BLE001 - the tool answers the model with the error
+            return describe_error(exc)
+        result = result or {}
+        names = [x.get("memory_name") for x in result.get("learning") or [] if x.get("memory_name")]
+        where = f' "{names[0]}"' if names else ""
+        if result.get("status") == "succeeded":
+            return f"Saved to Membase{where}; it is learned and searchable now."
+        return f"Saved to Membase{where}; it will be searchable once the Memory has learned it."
+
+    @tool(name="membase_profile", approval_mode="never_require")
+    async def membase_profile(ctx: FunctionInvocationContext | None = None) -> str:
+        """Read the user's Membase profile: standing statements about who they are (name, role,
+        lasting preferences), newest first. Read it once, near the start."""
+        try:
+            mb = _client(ctx)
+            p = await in_thread(mb.profile_facts.list)
+        except NoUserBound as exc:
+            return f"Membase is not available: {exc}."
+        except PermissionDeniedError as exc:
+            return (
+                "Membase refused the profile (403): this key's owner did not share the profile "
+                f"with it, or {REVOKED}. ({exc.message})"
+            )
+        except Exception as exc:  # noqa: BLE001 - the tool answers the model with the error
+            return describe_error(exc)
+        items = [str(x.get("content") or "").strip() for x in (p or {}).get("items") or []]
+        items = [x for x in items if x]
+        if not items:
+            return "The user's Membase profile is empty."
+        return "About the user:\n" + "\n".join(f"- {x}" for x in items)
+
+    tools: list[FunctionTool] = [membase_search]
+    if save:
+        tools.append(membase_save)
+    if profile:
+        tools.append(membase_profile)
+    return tools
+
+
+__all__ = ["membase_tools"]

agent_framework_membase-0.2.0/src/agent_framework_membase/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/tests/conftest.py

@@ -25,17 +25,27 @@ class FakeMembase:
 
     def __init__(self) -> None:
         self.requests: list[dict[str, Any]] = []
-        self.containers = [
-            {"id": "mv-decisions", "name": "Project decisions"},
-            {"id": "mv-travel", "name": "Travel"},
-        ]
+        self.write_target: str | None = "Travel"  # None: the key reaches several Memories
         self.results: list[dict[str, Any]] = [
-            {"content": "We settled on Postgres for the ledger.", "container_name": "Project decisions"},
+            {
+                "type": "memory",
+                "id": "mem_bGVkZ2Vy",
+                "content": "We settled on Postgres for the ledger.",
+                "score": 1.0,
+                "memory_name": "Project decisions",
+            },
         ]
-        self.container_errors: list[dict[str, Any]] = []
+        self.partial: list[dict[str, Any]] = []
         self.status: dict[str, int] = {}  # path -> forced status
         self.delay: float = 0.0
-        self.profile = {"static": ["Works in Berlin"], "dynamic": ["Prefers dark mode"], "results": []}
+        self.profile = {
+            "items": [
+                {"id": "pf_Mg", "content": "Works in Berlin", "source_kind": "user_stated"},
+                {"id": "pf_MQ", "content": "Prefers dark mode", "source_kind": "user_stated"},
+            ],
+            "has_more": False,
+            "partial": [],
+        }
 
     def handler(self, request: httpx.Request) -> httpx.Response:
         body = json.loads(request.content) if request.content else None
@@ -57,28 +67,24 @@ class FakeMembase:
                 forced, json={"error": {"code": "unauthorized", "message": f"forced {forced}"}}
             )
         if path == "/v1/search":
-            return httpx.Response(200, json={"results": self.results, "containers": self.container_errors})
-        if path == "/v1/containers":
-            return httpx.Response(200, json={"containers": self.containers})
-        if path == "/v1/profile":
+            if extra := set(body) - {"q", "limit", "mode"}:
+                return _error(422, "validation", f"unknown fields: {sorted(extra)}")
+            return httpx.Response(200, json={"items": self.results, "partial": self.partial})
+        if path == "/v1/profile-facts":
             return httpx.Response(200, json=self.profile)
-        if path == "/v1/memories":
-            if body.get("static"):
-                return httpx.Response(
-                    202, json={"static": True, "status": "recorded", "content": body["content"]}
-                )
-            if body.get("container") is None and len(self.containers) > 1:
-                return httpx.Response(
-                    400,
-                    json={
-                        "error": {
-                            "code": "validation",
-                            "message": "container is required with several in reach",
-                        }
-                    },
-                )
+        if path == "/v1/memories/add" and request.method == "POST":
+            if extra := set(body) - {"content", "title"}:
+                return _error(422, "validation", f"unknown fields: {sorted(extra)}")
+            if self.write_target is None:
+                return _error(422, "write_target_required", "reaches 2 Memories and has no write target")
             return httpx.Response(
-                202, json={"memory_id": "m1", "document_id": "d1", "status": "queued", "learning_run": None}
+                202,
+                json={
+                    "id": "doc_bm90ZQ",
+                    "kind": "note",
+                    "status": "processing",
+                    "learning": [{"memory_name": self.write_target, "status": "processing"}],
+                },
             )
         return httpx.Response(404, json={"error": {"code": "not_found", "message": path}})
 
@@ -90,6 +96,10 @@ class FakeMembase:
         return [r for r in self.requests if r["path"] == path]
 
 
+def _error(status: int, code: str, message: str) -> httpx.Response:
+    return httpx.Response(status, json={"error": {"code": code, "message": message}})
+
+
 class ScriptedChatClient(FunctionInvocationLayer[Any], BaseChatClient[Any]):
     """A chat client with no model: replays scripted responses and records every request."""
 

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/tests/test_provider.py

@@ -16,7 +16,7 @@ def _instructions(chat: ScriptedChatClient, i: int = 0) -> str:
     return str(chat.seen[i]["options"].get("instructions") or "")
 
 
-async def test_recall_injects_passages_citing_the_container(mem):
+async def test_recall_injects_passages_citing_the_memory(mem):
     chat = ScriptedChatClient([say("Postgres.")])
     agent = Agent(
         client=chat, instructions="Be brief.", context_providers=[MembaseContextProvider(mem.client())]
@@ -26,7 +26,7 @@ async def test_recall_injects_passages_citing_the_container(mem):
 
     assert result.text == "Postgres."
     (search,) = mem.calls("/v1/search")
-    assert search["json"] == {"q": "what did we decide about the ledger?", "limit": 8}
+    assert search["json"] == {"q": "what did we decide about the ledger?", "mode": "full", "limit": 8}
     text = _instructions(chat)
     assert text.startswith("Be brief.")
     assert "## Membase memory" in text
@@ -38,14 +38,12 @@ async def test_recall_injects_passages_citing_the_container(mem):
 
 async def test_recall_searches_only_the_latest_user_message(mem):
     chat = ScriptedChatClient()
-    agent = Agent(
-        client=chat, context_providers=[MembaseContextProvider(mem.client(), container="mv-decisions")]
-    )
+    agent = Agent(client=chat, context_providers=[MembaseContextProvider(mem.client())])
     session = agent.create_session()
     await agent.run("first question", session=session)
     await agent.run("second question", session=session)
     assert [c["json"]["q"] for c in mem.calls("/v1/search")] == ["first question", "second question"]
-    assert all(c["json"]["container"] == "mv-decisions" for c in mem.calls("/v1/search"))
+    assert all("container" not in c["json"] for c in mem.calls("/v1/search"))
 
 
 async def test_nothing_found_injects_nothing(mem):
@@ -60,15 +58,15 @@ async def test_nothing_found_injects_nothing(mem):
 
 async def test_a_memory_that_could_not_answer_is_reported_not_silent(mem, caplog):
     mem.results = []
-    mem.container_errors = [{"id": "mv-travel", "name": "Travel", "error": "no model configured"}]
+    mem.partial = [{"memory_name": "Travel", "reason": "error"}]
     chat = ScriptedChatClient()
     agent = Agent(client=chat, context_providers=[MembaseContextProvider(mem.client())])
     with caplog.at_level(logging.WARNING, logger="agent_framework_membase"):
         await agent.run("where am I flying next?")
     text = _instructions(chat)
-    assert '"Travel" could not answer: no model configured' in text
+    assert '"Travel" could not answer' in text
     assert "not evidence that nothing is stored" in text
-    assert "no model configured" in caplog.text
+    assert '"Travel" could not answer' in caplog.text
 
 
 async def test_cold_start_fails_open_within_the_budget(mem, caplog):
@@ -106,7 +104,7 @@ async def test_revoked_key_is_reported_and_not_retried(mem, caplog):
 async def test_capture_is_off_by_default(mem):
     agent = Agent(client=ScriptedChatClient(), context_providers=[MembaseContextProvider(mem.client())])
     await agent.run("remember that I take the window seat")
-    assert mem.calls("/v1/memories") == []
+    assert mem.calls("/v1/memories/add") == []
 
 
 async def test_capture_saves_the_users_words_once_per_turn(mem):
@@ -119,27 +117,25 @@ async def test_capture_saves_the_users_words_once_per_turn(mem):
         return "done"
 
     chat = ScriptedChatClient([call("noop", {}), say("Noted.")])
-    provider = MembaseContextProvider(mem.client(), capture=True, capture_container="mv-travel")
+    provider = MembaseContextProvider(mem.client(), capture=True)
     agent = Agent(client=chat, tools=[noop], context_providers=[provider])
     await agent.run("I always take the window seat")
-    (saved,) = mem.calls("/v1/memories")
+    (saved,) = mem.calls("/v1/memories/add")
     assert saved["json"] == {
         "content": "I always take the window seat",
-        "static": False,
         "title": "Agent Framework conversation",
-        "container": "mv-travel",
     }
     assert "confirm" not in saved["params"]
 
 
 async def test_capture_with_a_read_key_stops_after_the_refusal(mem, caplog):
-    mem.status["/v1/memories"] = 403
-    provider = MembaseContextProvider(mem.client(), capture=True, capture_container="mv-travel")
+    mem.status["/v1/memories/add"] = 403
+    provider = MembaseContextProvider(mem.client(), capture=True)
     agent = Agent(client=ScriptedChatClient(), context_providers=[provider])
     with caplog.at_level(logging.ERROR, logger="agent_framework_membase"):
         await agent.run("a")
         await agent.run("b")
-    assert len(mem.calls("/v1/memories")) == 1
+    assert len(mem.calls("/v1/memories/add")) == 1
     assert "a Read key cannot write" in caplog.text
 
 
@@ -211,9 +207,12 @@ def test_api_host_defaults_to_membase_com_whatever_the_sdk_defaults_to(monkeypat
     p.close()
 
 
-async def test_capture_without_a_container_explains_how_to_fix_it(mem, caplog):
+async def test_capture_without_a_write_target_explains_how_to_fix_it(mem, caplog):
+    mem.write_target = None
     provider = MembaseContextProvider(mem.client(), capture=True)
     agent = Agent(client=ScriptedChatClient(), context_providers=[provider])
     with caplog.at_level(logging.WARNING, logger="agent_framework_membase"):
         await agent.run("I always take the window seat")
-    assert "set capture_container=" in caplog.text
+        await agent.run("and the aisle on short flights")
+    assert len(mem.calls("/v1/memories/add")) == 1  # refused once, then not retried
+    assert "no write target" in caplog.text and "Connect › Developer keys" in caplog.text

{agent_framework_membase-0.1.0 → agent_framework_membase-0.2.0}/tests/test_tools.py

@@ -23,68 +23,57 @@ def test_tool_set_and_schemas(mem):
     search = tools[0].parameters()
     assert search["required"] == ["query"]
     assert "ctx" not in search["properties"]  # the framework injects it; the model never sees it
-    assert set(tools[1].parameters()["properties"]) == {"content", "container", "about_user"}
+    assert set(tools[1].parameters()["properties"]) == {"content"}
+    assert "container" not in search["properties"]
     assert [t.name for t in membase_tools(mem.client(), save=False, profile=False)] == ["membase_search"]
 
 
-async def test_search_cites_the_container(mem):
-    _, (out,) = await _run(mem, [call("membase_search", {"query": "ledger"})])
+async def test_search_cites_the_memory(mem):
+    _, (out,) = await _run(mem, [call("membase_search", {"query": "ledger", "limit": 3})])
     assert "- [Project decisions] We settled on Postgres for the ledger." in out
-    assert mem.calls("/v1/search")[0]["json"] == {"q": "ledger"}
-
-
-async def test_search_by_container_name_resolves_to_its_id(mem):
-    _, _ = await _run(mem, [call("membase_search", {"query": "flights", "container": "travel", "limit": 3})])
-    assert mem.calls("/v1/search")[0]["json"] == {"q": "flights", "container": "mv-travel", "limit": 3}
+    assert mem.calls("/v1/search")[0]["json"] == {"q": "ledger", "mode": "full", "limit": 3}
 
 
 async def test_search_reports_memories_that_could_not_answer(mem):
     mem.results = []
-    mem.container_errors = [{"id": "mv-travel", "name": "Travel", "error": "dormant"}]
+    mem.partial = [
+        {"memory_name": "Travel", "reason": "error"},
+        {"memory_name": "Reading", "reason": "truncated"},
+    ]
     _, (out,) = await _run(mem, [call("membase_search", {"query": "x"})])
-    assert "No passages" in out and '"Travel" could not answer: dormant' in out
+    assert "No passages" in out and '"Travel" could not answer' in out
+    assert '"Reading" had more passages than the limit let through' in out
 
 
-async def test_save_to_a_named_memory(mem):
-    _, (out,) = await _run(
-        mem, [call("membase_save", {"content": "I take the window seat", "container": "Travel"})]
-    )
-    (saved,) = mem.calls("/v1/memories")
-    assert saved["json"] == {
-        "content": "I take the window seat",
-        "static": False,
-        "title": "",
-        "container": "mv-travel",
-    }
+async def test_save_lands_in_the_write_target(mem):
+    _, (out,) = await _run(mem, [call("membase_save", {"content": "I take the window seat"})])
+    (saved,) = mem.calls("/v1/memories/add")
+    assert saved["json"] == {"content": "I take the window seat", "title": ""}
     assert saved["params"] == {}  # never confirm=
     assert 'Saved to Membase "Travel"' in out
 
 
-async def test_save_without_a_container_lists_the_choices(mem):
+async def test_save_without_a_write_target_says_how_to_fix_it(mem):
+    mem.write_target = None
     _, (out,) = await _run(mem, [call("membase_save", {"content": "x"})])
-    assert '"Project decisions", "Travel"' in out and "did not save" in out
-
-
-async def test_save_about_the_user_goes_to_the_profile(mem):
-    _, (out,) = await _run(mem, [call("membase_save", {"content": "I am vegetarian", "about_user": True})])
-    assert mem.calls("/v1/memories")[0]["json"]["static"] is True
-    assert out == "Recorded in the user's Membase profile."
+    assert "did not save" in out and "several Memories and has no write target" in out
+    assert "Connect › Developer keys" in out
 
 
 async def test_save_with_a_read_key_explains_the_refusal(mem):
-    mem.status["/v1/memories"] = 403
-    _, (out,) = await _run(mem, [call("membase_save", {"content": "x", "container": "Travel"})])
+    mem.status["/v1/memories/add"] = 403
+    _, (out,) = await _run(mem, [call("membase_save", {"content": "x"})])
     assert "narrowed or revoked" in out and "Read key cannot write" in out
 
 
 async def test_profile(mem):
     _, (out,) = await _run(mem, [call("membase_profile", {})])
-    assert "Standing facts:\n- Works in Berlin" in out and "Recently changed:\n- Prefers dark mode" in out
+    assert out == "About the user:\n- Works in Berlin\n- Prefers dark mode"
 
 
 async def test_profile_not_shared_is_a_clear_message(mem):
-    mem.status["/v1/profile"] = 403
-    _, (out,) = await _run(mem, [call("membase_profile", {"topic": "food"})])
+    mem.status["/v1/profile-facts"] = 403
+    _, (out,) = await _run(mem, [call("membase_profile", {})])
     assert "did not share the profile" in out
 
 
@@ -109,7 +98,7 @@ async def test_provider_and_tools_together(mem):
     client = mem.client()
     chat = ScriptedChatClient(
         [
-            call("membase_save", {"content": "Ship on Fridays", "container": "Project decisions"}),
+            call("membase_save", {"content": "Ship on Fridays"}),
             say("Saved."),
         ]
     )
@@ -119,4 +108,4 @@ async def test_provider_and_tools_together(mem):
     result = await agent.run("remember: we ship on Fridays")
     assert result.text == "Saved."
     assert "[Project decisions]" in str(chat.seen[0]["options"]["instructions"])
-    assert mem.calls("/v1/memories")[0]["json"]["content"] == "Ship on Fridays"
+    assert mem.calls("/v1/memories/add")[0]["json"]["content"] == "Ship on Fridays"

agent_framework_membase-0.1.0/src/agent_framework_membase/_tools.py

@@ -1,207 +0,0 @@
-"""``membase_tools``: search, save and profile as Agent Framework function tools."""
-
-from __future__ import annotations
-
-import os
-from typing import Annotated, Any
-
-from agent_framework import FunctionInvocationContext, FunctionTool, tool
-from membase import Membase
-from membase.errors import BadRequestError, MembaseError, PermissionDeniedError
-from pydantic import Field
-
-from ._common import (
-    DEFAULT_SOURCE_ID,
-    REVOKED,
-    ClientFor,
-    Clients,
-    NoUserBound,
-    describe_error,
-    format_search,
-    in_thread,
-)
-
-
-def _resolve_container(client: Membase, wanted: str) -> tuple[str | None, str]:
-    """``(container_id, name)`` for a container given by id or by name, else ``(None, message)``."""
-    containers = client.containers.list().get("containers") or []
-    key = wanted.strip().casefold()
-    for c in containers:
-        if str(c.get("id", "")) == wanted.strip():
-            return str(c["id"]), str(c.get("name") or c["id"])
-    for c in containers:
-        if str(c.get("name", "")).strip().casefold() == key:
-            return str(c["id"]), str(c.get("name") or c["id"])
-    names = ", ".join(f'"{c.get("name")}"' for c in containers) or "none"
-    return None, f'No Memory called "{wanted}" is in reach of this key. Memories in reach: {names}.'
-
-
-def _names(client: Membase) -> str:
-    try:
-        containers = client.containers.list().get("containers") or []
-    except MembaseError:
-        return ""
-    return ", ".join(f'"{c.get("name")}"' for c in containers)
-
-
-def membase_tools(
-    client: Membase | None = None,
-    *,
-    api_key: str | None = None,
-    base_url: str | None = None,
-    local: str | os.PathLike[str] | bool | None = None,
-    client_for: ClientFor | None = None,
-    source_id: str = DEFAULT_SOURCE_ID,
-    save: bool = True,
-    profile: bool = True,
-) -> list[FunctionTool]:
-    """Membase as Agent Framework function tools: ``membase_search``, ``membase_save``,
-    ``membase_profile``.
-
-    Pass a ready ``Membase`` client, or ``api_key`` / ``base_url`` / ``local``, or
-    ``client_for`` (``user_id -> Membase``) with the user bound to each session by
-    :func:`bind_user` (the same binding :class:`MembaseContextProvider` reads). Tool calls use
-    the SDK's own timeout (90 s by default), since the model asked for them explicitly.
-
-    ``save=False`` leaves out ``membase_save`` (for a Read key); ``profile=False`` leaves out
-    ``membase_profile`` (for a key whose owner did not share the profile). There is no delete
-    or forget tool.
-    """
-    clients = Clients(
-        client, api_key=api_key, base_url=base_url, local=local, client_for=client_for, source_id=source_id
-    )
-
-    def _client(ctx: FunctionInvocationContext | None) -> Membase:
-        return clients.for_session(ctx.session if ctx is not None else None)
-
-    @tool(name="membase_search", approval_mode="never_require")
-    async def membase_search(
-        query: Annotated[str, Field(description="What to look for, in natural language.")],
-        container: Annotated[
-            str | None,
-            Field(
-                description="Only this Memory (its name as shown in results). Omit to search every Memory."
-            ),
-        ] = None,
-        limit: Annotated[int | None, Field(description="How many passages, 1-50.", ge=1, le=50)] = None,
-        ctx: FunctionInvocationContext | None = None,
-    ) -> str:
-        """Search the user's long-term Membase memory. Returns passages, each tagged with the
-        Memory it came from; name that Memory when you use a passage."""
-        try:
-            mb = _client(ctx)
-            container_id = None
-            if container:
-                container_id, note = await in_thread(_resolve_container, mb, container)
-                if container_id is None:
-                    return note
-            answer = await in_thread(mb.search, query, container=container_id, limit=limit)
-        except NoUserBound as exc:
-            return f"Membase is not available: {exc}."
-        except Exception as exc:  # noqa: BLE001 - the tool answers the model with the error
-            return describe_error(exc)
-        passages, unanswered = format_search(answer)
-        out = (
-            ["Passages from the user's Membase memory:", *passages]
-            if passages
-            else ["No passages in the user's Membase memory matched."]
-        )
-        if unanswered:
-            out += ["These Memories could not answer, so this is not proof nothing is stored:", *unanswered]
-        return "\n".join(out)
-
-    @tool(name="membase_save", approval_mode="never_require")
-    async def membase_save(
-        content: Annotated[
-            str, Field(description="The fact to keep, in the user's own words. One fact per call.")
-        ],
-        container: Annotated[
-            str | None,
-            Field(description="The Memory that keeps it (its name). Needed when the user has several."),
-        ] = None,
-        about_user: Annotated[
-            bool,
-            Field(
-                description=(
-                    "True for a standing fact about the user themselves (who they are, a lasting "
-                    "preference): it goes to their profile instead of a Memory."
-                )
-            ),
-        ] = False,
-        ctx: FunctionInvocationContext | None = None,
-    ) -> str:
-        """Save something to the user's Membase memory. Call this only when the user asks you
-        to remember something or plainly means it; never save your own conclusions."""
-        try:
-            mb = _client(ctx)
-            container_id, name = None, ""
-            if container and not about_user:
-                container_id, name = await in_thread(_resolve_container, mb, container)
-                if container_id is None:
-                    return name
-            result = await in_thread(mb.memories.add, content, container=container_id, static=about_user)
-        except NoUserBound as exc:
-            return f"Membase is not available: {exc}."
-        except BadRequestError as exc:
-            names = await in_thread(_names, mb)
-            hint = f" Pass container= with one of: {names}." if names and not container else ""
-            return f"Membase did not save it: {exc.message}.{hint}"
-        except PermissionDeniedError as exc:
-            return f"Membase did not save it (403): {REVOKED}; a Read key cannot write. ({exc.message})"
-        except Exception as exc:  # noqa: BLE001 - the tool answers the model with the error
-            return describe_error(exc)
-        if (result or {}).get("static"):
-            return "Recorded in the user's Membase profile."
-        where = f' "{name}"' if name else ""
-        return f"Saved to Membase{where}; it is queued and will be searchable once the Memory has learned it."
-
-    @tool(name="membase_profile", approval_mode="never_require")
-    async def membase_profile(
-        topic: Annotated[
-            str | None, Field(description="Optional topic to pull relevant profile facts for.")
-        ] = None,
-        ctx: FunctionInvocationContext | None = None,
-    ) -> str:
-        """Read the user's Membase profile: standing facts about who they are and their
-        preferences, and the most recently changed ones. Read it once, near the start."""
-        try:
-            mb = _client(ctx)
-            p = await in_thread(mb.profile, topic)
-        except NoUserBound as exc:
-            return f"Membase is not available: {exc}."
-        except PermissionDeniedError as exc:
-            return (
-                "Membase refused the profile (403): this key's owner did not share the profile "
-                f"with it, or {REVOKED}. ({exc.message})"
-            )
-        except Exception as exc:  # noqa: BLE001 - the tool answers the model with the error
-            return describe_error(exc)
-        out: list[str] = []
-        for label, key in (
-            ("Standing facts", "static"),
-            ("Recently changed", "dynamic"),
-            ("On the topic", "results"),
-        ):
-            items = [_text(x) for x in (p or {}).get(key) or []]
-            items = [x for x in items if x]
-            if items:
-                out.append(f"{label}:\n" + "\n".join(f"- {x}" for x in items))
-        return "\n\n".join(out) or "The user's Membase profile is empty."
-
-    tools: list[FunctionTool] = [membase_search]
-    if save:
-        tools.append(membase_save)
-    if profile:
-        tools.append(membase_profile)
-    return tools
-
-
-def _text(item: Any) -> str:
-    if isinstance(item, str):
-        return item.strip()
-    if isinstance(item, dict):
-        return str(item.get("content") or item.get("text") or item.get("memory") or "").strip()
-    return str(item).strip()
-
-
-__all__ = ["membase_tools"]

agent_framework_membase-0.1.0/src/agent_framework_membase/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"