membase-strands 0.1.0__tar.gz

membase_strands-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+.pytest_cache/
+.ruff_cache/

membase_strands-0.1.0/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.

membase_strands-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: membase-strands
+Version: 0.1.0
+Summary: Membase memory for Strands Agents: a MemoryStore with time-boxed recall and deliberate search/save/profile tools.
+Project-URL: Homepage, https://membase.com
+Project-URL: Documentation, https://github.com/unibaseio/membase/tree/main/integrations/strands#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,long-term-memory,membase,memory,strands,strands-agents
+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: strands-agents>=1.45.0
+Requires-Dist: unibaseio-membase>=0.3.2
+Provides-Extra: local
+Requires-Dist: unibaseio-membase[local]>=0.3.2; extra == 'local'
+Description-Content-Type: text/markdown
+
+# membase-strands
+
+[Membase](https://membase.com) memory for [Strands Agents](https://strandsagents.com) (Python).
+
+`MembaseMemoryStore` implements Strands' `MemoryStore` protocol, so it plugs into
+`strands.memory.MemoryManager` like the other memory stores:
+
+- **Recall before each user turn.** The manager's context injection calls `search`, and the
+  passages it returns are folded into that model call. Each one names the Membase memory
+  (container) it came from: `[Project decisions] We chose Postgres for the ledger.`
+- **Time-boxed, fail-open recall.** A Membase search runs inside the account's own memory
+  container, and the first one after a quiet spell takes longer while it wakes. The
+  automatic recall gets 8 seconds by default (`recall_timeout`). If it runs out, the manager
+  logs it and the turn goes ahead without memory. The request keeps running in the
+  background, so the memory is awake for the next turn. While it is still running, later
+  recalls skip immediately instead of piling up.
+- **Deliberate writes.** `get_tools()` gives the model `membase_search`, `membase_save` and
+  `membase_profile`. Saving is a tool the model calls when the user asked it to remember
+  something. Saving every turn automatically (`capture=True`) is opt-in.
+
+```bash
+pip install membase-strands
+```
+
+## Quick start
+
+Create a developer key in the Membase app under **Connect › Developer keys**. Use
+*Read & write* if the agent should save, and tick the profile if it should read it.
+
+```python
+from strands import Agent
+from strands.memory import MemoryManager
+from membase_strands import MembaseMemoryStore
+
+store = MembaseMemoryStore(api_key="mbk_...")       # or set MEMBASE_API_KEY
+
+agent = Agent(
+    memory_manager=MemoryManager(
+        stores=[store],
+        search_tool_config=False,   # the model gets membase_search instead (see below)
+    ),
+)
+
+agent("Which database did we pick for the ledger?")
+# Before the model call, the manager searches Membase and injects:
+# <memory>
+# <entry source="membase">[Project decisions] We chose Postgres for the ledger.</entry>
+# </memory>
+
+agent("Remember that we moved the launch to May.")
+# The model calls membase_save(content="We moved the launch to May.", container="Project decisions")
+```
+
+### Why `search_tool_config=False`
+
+The manager's built-in `search_memory` tool calls the same time-boxed `search` as injection.
+On a cold start it would give up after 8 seconds and show the model an empty list. The
+store's own `membase_search` tool waits for the SDK's full timeout (90 s), so a cold start
+gets an answer. It also lets the model pick one Memory by name, and it says when a Memory
+could not answer. You can keep both tools if you prefer.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `membase_search(query, container?, limit?)` | Searches every Memory in reach, or one Memory by name or id. Each passage is cited as `[Memory name] …`. A Memory that could not answer is listed as such, so it is not mistaken for "no memory". |
+| `membase_save(content, container?, standing_fact?)` | Saves a note in the user's words. `standing_fact=true` records a lasting fact in the user's profile. If the key reaches several Memories and none is named, the tool returns their names so the model can ask which one. |
+| `membase_profile(topic?)` | Reads the user's standing facts and recent changes. This needs the owner to have ticked the profile for the key. |
+
+Pick the tools with `tools=("search", "profile")`. For example, drop `"save"` for a Read key.
+There is no delete or forget tool, and the store never confirms a destructive operation for
+the user.
+
+## Options
+
+```python
+MembaseMemoryStore(
+    client=None,              # a ready membase.Membase client, or:
+    api_key=None,             #   MEMBASE_API_KEY
+    base_url=None,            #   MEMBASE_BASE_URL, default https://api.app.membase.com
+    local=None,               #   a directory for local mode (pip install 'membase-strands[local]')
+    container=None,           # one Memory (name or id) to search and write to; default: all in reach
+    name="membase",           # store name in the manager
+    max_search_results=None,  # passages per search when the caller passes none (default 5)
+    recall_timeout=8.0,       # budget for the automatic recall; None = SDK timeout
+    capture=False,            # let the manager write (add_memory tool, extraction)
+    extraction=None,          # the manager's extraction config; needs capture=True
+    capture_roles=("user",),  # which messages captured turns keep
+    tools=("search", "save", "profile"),
+)
+```
+
+### Automatic capture (opt-in)
+
+By default the store is not `writable`, so the manager never writes to Membase. The only way
+to save is the model calling `membase_save` when the user asks. Membase learns from what it
+is given, and a transcript of every turn would teach it the assistant's own answers as facts.
+
+To capture anyway:
+
+```python
+store = MembaseMemoryStore(container="Conversations", capture=True, extraction=True)
+agent = Agent(memory_manager=MemoryManager(stores=[store], search_tool_config=False))
+```
+
+With `extraction=True` the manager hands batches of turns to `add_messages`, by default every
+5 turns and at the end of each synchronous `agent(...)` call. The store saves the user's
+messages from the batch as one note in `container`, and Membase learns from it in the
+background. `capture_roles=("user", "assistant")` keeps both sides. `capture=True` also lets
+you enable the manager's own `add_memory` tool (`MemoryManager(..., add_tool_config=True)`).
+A retried batch can be saved twice.
+
+## One store per person
+
+Membase has no `user_id`. One key, or one local directory, is one person's account. The
+`MemoryStore` protocol does not pass a user or session to `search` either. So a store built
+from a single key suits **a personal agent**. In a multi-user app, build the store and the
+agent per user, from that user's own key or directory, and never route one user's turn
+through another user's key:
+
+```python
+def agent_for(user) -> Agent:
+    store = MembaseMemoryStore(api_key=keys.get(user.id))           # that user's key
+    # or: MembaseMemoryStore(local=f"/data/membase/{user.id}")      # one directory per user
+    return Agent(memory_manager=MemoryManager(stores=[store], search_tool_config=False))
+```
+
+## Errors
+
+- **403** means the key's owner narrowed or revoked it. Automatic recall raises
+  `MembaseAccessError`; the manager logs it and continues without memory. The tools return
+  "this Membase key was narrowed or revoked…" so the model can tell the user. Nothing retries
+  with that key.
+- **A Memory that could not answer** (no working model, dormant) is reported. Recall returns
+  an entry that says so, and `membase_search` lists it under "Not searched".
+- **A recall that runs out of time** raises `MembaseRecallTimeout` (a `TimeoutError`); the
+  manager logs it and continues. The tools use the SDK timeout and, if that runs out too,
+  return a "try again in a minute" sentence.
+- Captured writes (`add`, `add_messages`) raise on failure so the manager can report or retry
+  them. The tools turn errors into sentences.
+
+The key is never logged.
+
+## Compatibility
+
+Python 3.10+, `strands-agents>=1.45.0` (the first release with `strands.memory`) and
+`unibaseio-membase>=0.3.2`. The offline tests pass on strands-agents 1.45.0, 1.50.0, 1.55.0
+and 1.61.1.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . pytest pytest-asyncio ruff
+.venv/bin/python -m pytest -q                       # offline: real Strands Agent, Membase SDK on httpx.MockTransport
+MEMBASE_API_KEY=mbk_... .venv/bin/python examples/live_smoke.py
+uv build
+```
+
+MIT licence.

membase_strands-0.1.0/README.md

@@ -0,0 +1,159 @@
+# membase-strands
+
+[Membase](https://membase.com) memory for [Strands Agents](https://strandsagents.com) (Python).
+
+`MembaseMemoryStore` implements Strands' `MemoryStore` protocol, so it plugs into
+`strands.memory.MemoryManager` like the other memory stores:
+
+- **Recall before each user turn.** The manager's context injection calls `search`, and the
+  passages it returns are folded into that model call. Each one names the Membase memory
+  (container) it came from: `[Project decisions] We chose Postgres for the ledger.`
+- **Time-boxed, fail-open recall.** A Membase search runs inside the account's own memory
+  container, and the first one after a quiet spell takes longer while it wakes. The
+  automatic recall gets 8 seconds by default (`recall_timeout`). If it runs out, the manager
+  logs it and the turn goes ahead without memory. The request keeps running in the
+  background, so the memory is awake for the next turn. While it is still running, later
+  recalls skip immediately instead of piling up.
+- **Deliberate writes.** `get_tools()` gives the model `membase_search`, `membase_save` and
+  `membase_profile`. Saving is a tool the model calls when the user asked it to remember
+  something. Saving every turn automatically (`capture=True`) is opt-in.
+
+```bash
+pip install membase-strands
+```
+
+## Quick start
+
+Create a developer key in the Membase app under **Connect › Developer keys**. Use
+*Read & write* if the agent should save, and tick the profile if it should read it.
+
+```python
+from strands import Agent
+from strands.memory import MemoryManager
+from membase_strands import MembaseMemoryStore
+
+store = MembaseMemoryStore(api_key="mbk_...")       # or set MEMBASE_API_KEY
+
+agent = Agent(
+    memory_manager=MemoryManager(
+        stores=[store],
+        search_tool_config=False,   # the model gets membase_search instead (see below)
+    ),
+)
+
+agent("Which database did we pick for the ledger?")
+# Before the model call, the manager searches Membase and injects:
+# <memory>
+# <entry source="membase">[Project decisions] We chose Postgres for the ledger.</entry>
+# </memory>
+
+agent("Remember that we moved the launch to May.")
+# The model calls membase_save(content="We moved the launch to May.", container="Project decisions")
+```
+
+### Why `search_tool_config=False`
+
+The manager's built-in `search_memory` tool calls the same time-boxed `search` as injection.
+On a cold start it would give up after 8 seconds and show the model an empty list. The
+store's own `membase_search` tool waits for the SDK's full timeout (90 s), so a cold start
+gets an answer. It also lets the model pick one Memory by name, and it says when a Memory
+could not answer. You can keep both tools if you prefer.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `membase_search(query, container?, limit?)` | Searches every Memory in reach, or one Memory by name or id. Each passage is cited as `[Memory name] …`. A Memory that could not answer is listed as such, so it is not mistaken for "no memory". |
+| `membase_save(content, container?, standing_fact?)` | Saves a note in the user's words. `standing_fact=true` records a lasting fact in the user's profile. If the key reaches several Memories and none is named, the tool returns their names so the model can ask which one. |
+| `membase_profile(topic?)` | Reads the user's standing facts and recent changes. This needs the owner to have ticked the profile for the key. |
+
+Pick the tools with `tools=("search", "profile")`. For example, drop `"save"` for a Read key.
+There is no delete or forget tool, and the store never confirms a destructive operation for
+the user.
+
+## Options
+
+```python
+MembaseMemoryStore(
+    client=None,              # a ready membase.Membase client, or:
+    api_key=None,             #   MEMBASE_API_KEY
+    base_url=None,            #   MEMBASE_BASE_URL, default https://api.app.membase.com
+    local=None,               #   a directory for local mode (pip install 'membase-strands[local]')
+    container=None,           # one Memory (name or id) to search and write to; default: all in reach
+    name="membase",           # store name in the manager
+    max_search_results=None,  # passages per search when the caller passes none (default 5)
+    recall_timeout=8.0,       # budget for the automatic recall; None = SDK timeout
+    capture=False,            # let the manager write (add_memory tool, extraction)
+    extraction=None,          # the manager's extraction config; needs capture=True
+    capture_roles=("user",),  # which messages captured turns keep
+    tools=("search", "save", "profile"),
+)
+```
+
+### Automatic capture (opt-in)
+
+By default the store is not `writable`, so the manager never writes to Membase. The only way
+to save is the model calling `membase_save` when the user asks. Membase learns from what it
+is given, and a transcript of every turn would teach it the assistant's own answers as facts.
+
+To capture anyway:
+
+```python
+store = MembaseMemoryStore(container="Conversations", capture=True, extraction=True)
+agent = Agent(memory_manager=MemoryManager(stores=[store], search_tool_config=False))
+```
+
+With `extraction=True` the manager hands batches of turns to `add_messages`, by default every
+5 turns and at the end of each synchronous `agent(...)` call. The store saves the user's
+messages from the batch as one note in `container`, and Membase learns from it in the
+background. `capture_roles=("user", "assistant")` keeps both sides. `capture=True` also lets
+you enable the manager's own `add_memory` tool (`MemoryManager(..., add_tool_config=True)`).
+A retried batch can be saved twice.
+
+## One store per person
+
+Membase has no `user_id`. One key, or one local directory, is one person's account. The
+`MemoryStore` protocol does not pass a user or session to `search` either. So a store built
+from a single key suits **a personal agent**. In a multi-user app, build the store and the
+agent per user, from that user's own key or directory, and never route one user's turn
+through another user's key:
+
+```python
+def agent_for(user) -> Agent:
+    store = MembaseMemoryStore(api_key=keys.get(user.id))           # that user's key
+    # or: MembaseMemoryStore(local=f"/data/membase/{user.id}")      # one directory per user
+    return Agent(memory_manager=MemoryManager(stores=[store], search_tool_config=False))
+```
+
+## Errors
+
+- **403** means the key's owner narrowed or revoked it. Automatic recall raises
+  `MembaseAccessError`; the manager logs it and continues without memory. The tools return
+  "this Membase key was narrowed or revoked…" so the model can tell the user. Nothing retries
+  with that key.
+- **A Memory that could not answer** (no working model, dormant) is reported. Recall returns
+  an entry that says so, and `membase_search` lists it under "Not searched".
+- **A recall that runs out of time** raises `MembaseRecallTimeout` (a `TimeoutError`); the
+  manager logs it and continues. The tools use the SDK timeout and, if that runs out too,
+  return a "try again in a minute" sentence.
+- Captured writes (`add`, `add_messages`) raise on failure so the manager can report or retry
+  them. The tools turn errors into sentences.
+
+The key is never logged.
+
+## Compatibility
+
+Python 3.10+, `strands-agents>=1.45.0` (the first release with `strands.memory`) and
+`unibaseio-membase>=0.3.2`. The offline tests pass on strands-agents 1.45.0, 1.50.0, 1.55.0
+and 1.61.1.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . pytest pytest-asyncio ruff
+.venv/bin/python -m pytest -q                       # offline: real Strands Agent, Membase SDK on httpx.MockTransport
+MEMBASE_API_KEY=mbk_... .venv/bin/python examples/live_smoke.py
+uv build
+```
+
+MIT licence.

membase_strands-0.1.0/examples/live_smoke.py

@@ -0,0 +1,90 @@
+"""Live smoke test against the real Membase API.
+
+Needs MEMBASE_API_KEY (a developer key from Connect > Developer keys in the Membase app).
+Without a model key it checks the store and its tools directly; with AWS credentials for
+Bedrock (Strands' default model) or OPENAI_API_KEY plus `pip install 'strands-agents[openai]'`,
+it also runs one agent turn so injection is exercised end to end.
+
+    MEMBASE_API_KEY=mbk_... python examples/live_smoke.py
+    MEMBASE_API_KEY=mbk_... MEMBASE_SMOKE_SAVE=1 python examples/live_smoke.py   # also saves one note
+
+Saving is off unless MEMBASE_SMOKE_SAVE=1, because it writes to a real person's memory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+import time
+
+from membase_strands import MembaseMemoryStore
+
+
+def tool(store: MembaseMemoryStore, name: str):
+    return next(t for t in store.get_tools() if t.tool_name == name)
+
+
+async def main() -> int:
+    if not os.environ.get("MEMBASE_API_KEY"):
+        print("MEMBASE_API_KEY is not set; nothing to do.")
+        return 0
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    store = MembaseMemoryStore()  # MEMBASE_API_KEY / MEMBASE_BASE_URL from the environment
+    containers = store.client.containers.list()["containers"]
+    print("Memories in reach:", [c["name"] for c in containers])
+
+    # 1. Explicit search through the tool (SDK timeout, so a cold start is waited out).
+    started = time.monotonic()
+    out = await tool(store, "membase_search")(query="what do I care about?")
+    print(f"\nmembase_search ({time.monotonic() - started:.1f}s):\n{out}")
+
+    # 2. Automatic recall path: time-boxed; now warm, it should answer within budget.
+    started = time.monotonic()
+    try:
+        entries = await store.search("what do I care about?")
+        print(f"\nstore.search ({time.monotonic() - started:.1f}s): {len(entries)} entries")
+        for e in entries:
+            print("  ", e.content[:160])
+    except TimeoutError as error:
+        print(f"\nstore.search timed out as designed: {error}")
+
+    # 3. Profile (403 if the owner did not share the profile with this key).
+    print("\nmembase_profile:\n" + await tool(store, "membase_profile")())
+
+    if os.environ.get("MEMBASE_SMOKE_SAVE") == "1":
+        target = containers[0]["name"] if containers else None
+        out = await tool(store, "membase_save")(
+            content="Membase Strands smoke test: this note can be deleted.", container=target
+        )
+        print("\nmembase_save:", out)
+
+    # 4. One real agent turn, if a model is configured.
+    model = None
+    if os.environ.get("OPENAI_API_KEY"):
+        from strands.models.openai import OpenAIModel
+
+        model = OpenAIModel(model_id=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"))
+    elif os.environ.get("AWS_ACCESS_KEY_ID") or os.environ.get("AWS_PROFILE"):
+        model = None  # Strands' default Bedrock model
+    else:
+        print("\nNo model credentials; skipping the agent turn.")
+        return 0
+
+    from strands import Agent
+    from strands.memory import MemoryManager
+
+    agent = Agent(
+        model=model,
+        memory_manager=MemoryManager(stores=[store], search_tool_config=False),
+        system_prompt="Answer from the user's memory when it helps, and name the Memory you used.",
+    )
+    result = await agent.invoke_async("What do you remember about me? One sentence.")
+    print("\nAgent:", result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

membase_strands-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "membase-strands"
+version = "0.1.0"
+description = "Membase memory for Strands Agents: a MemoryStore with time-boxed recall and deliberate search/save/profile tools."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Unibase" }]
+keywords = ["strands", "strands-agents", "agents", "memory", "membase", "long-term-memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# strands-agents>=1.45.0: first release with strands.memory (MemoryStore / MemoryManager,
+# injection, get_tools). The offline tests pass on 1.45.0, 1.50.0, 1.55.0 and 1.61.1.
+dependencies = [
+    "strands-agents>=1.45.0",
+    "unibaseio-membase>=0.3.2",
+]
+
+[project.optional-dependencies]
+local = ["unibaseio-membase[local]>=0.3.2"]
+
+[project.urls]
+Homepage = "https://membase.com"
+Documentation = "https://github.com/unibaseio/membase/tree/main/integrations/strands#readme"
+Repository = "https://github.com/unibaseio/membase"
+Issues = "https://github.com/unibaseio/membase/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/membase_strands"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

membase_strands-0.1.0/src/membase_strands/__init__.py

@@ -0,0 +1,16 @@
+"""Membase memory for Strands Agents: a ``MemoryStore`` plus deliberate search/save/profile tools."""
+
+from .store import (
+    DEFAULT_RECALL_TIMEOUT,
+    MembaseAccessError,
+    MembaseMemoryStore,
+    MembaseRecallTimeout,
+)
+
+__all__ = [
+    "DEFAULT_RECALL_TIMEOUT",
+    "MembaseAccessError",
+    "MembaseMemoryStore",
+    "MembaseRecallTimeout",
+]
+__version__ = "0.1.0"