memwal 0.1.4.dev0__tar.gz → 0.1.4.dev1__tar.gz

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/.gitignore

@@ -60,6 +60,8 @@ share/python-wheels/
 # Jupyter
 .ipynb_checkpoints/
 *.ipynb
+!notebooks/
+!notebooks/walrus_memory_python_sdk.ipynb
 
 # Docs build
 site/

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # memwal
 
+## Unreleased
+
+### Added
+
+- Added a runnable [Walrus Memory Python SDK Colab](https://colab.research.google.com/drive/1SaKjkSp0DXnM_nktWSiEC-l9qGtVr6ph) covering installation, secure `staging` configuration, optional `prod`, `MemWalSync`, health/compatibility checks, delegate public-key/address derivation, `remember`, `remember_async`, async job waiting, `recall`, bulk remember, `remember_bulk_async`, `remember_bulk_and_wait`, optional `ask`, `analyze`, `analyze_and_wait`, `embed`, manual methods with scoring weights, `restore`, optional OpenAI/LangChain middleware, OpenAI-compatible provider settings such as `OPENAI_BASE_URL`, and troubleshooting.
+
+### Fixed
+
+- Fixed `MemWalSync` reuse inside notebooks so repeated calls do not reuse an HTTP transport from a closed event loop.
+
 ## 0.1.4
 
 ### Added

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memwal
-Version: 0.1.4.dev0
+Version: 0.1.4.dev1
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memwal.ai
 Project-URL: Documentation, https://docs.memwal.ai
@@ -57,6 +57,10 @@ pip install memwal[openai]      # OpenAI SDK support
 pip install memwal[all]         # Everything
 ```
 
+## Try It In Colab
+
+Open the runnable [Walrus Memory Python SDK Colab](https://colab.research.google.com/drive/1SaKjkSp0DXnM_nktWSiEC-l9qGtVr6ph) for a notebook walkthrough covering installation, secure `staging` configuration, optional `prod`, health checks, `remember`, `remember_async`, async job waiting, `recall`, bulk remember, `remember_bulk_async`, `remember_bulk_and_wait`, optional SDK utilities, OpenAI/LangChain middleware, OpenAI-compatible provider settings such as `OPENAI_BASE_URL`, and troubleshooting.
+
 ## Quick Start
 
 Set your environment variables first:
@@ -84,8 +88,8 @@ async def main():
         server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
     )
 
-    # Store a memory
-    result = await memwal.remember("I'm allergic to peanuts")
+    # Store a memory and wait until the background job is searchable
+    result = await memwal.remember_and_wait("I'm allergic to peanuts")
     print(result.blob_id)
 
     # Recall memories
@@ -93,8 +97,8 @@ async def main():
     for memory in matches.results:
         print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
 
-    # Analyze conversation for facts
-    analysis = await memwal.analyze("I love coffee and live in Tokyo")
+    # Analyze conversation for facts and wait until extracted facts are searchable
+    analysis = await memwal.analyze_and_wait("I love coffee and live in Tokyo")
     for fact in analysis.facts:
         print(fact.text)
 
@@ -115,7 +119,7 @@ client = MemWalSync.create(
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
 )
 
-result = client.remember("I'm allergic to peanuts")
+result = client.remember_and_wait("I'm allergic to peanuts")
 matches = client.recall(RecallParams(query="food allergies"))
 client.close()
 ```
@@ -130,7 +134,7 @@ async with MemWal.create(
     key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
 ) as memwal:
-    await memwal.remember("I prefer dark mode")
+    await memwal.remember_and_wait("I prefer dark mode")
 ```
 
 ## Environment Presets
@@ -144,16 +148,14 @@ from memwal import MemWal
 memwal = MemWal.create(
     key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
-    env="prod",   # prod | dev | staging | local
+    env="staging",   # staging for testing, prod for production
 )
 ```
 
 | `env` | Relayer URL |
 |-------|-------------|
 | `prod` | `https://relayer.memwal.ai` |
-| `dev` | `https://relayer.dev.memwal.ai` |
 | `staging` | `https://relayer.staging.memwal.ai` |
-| `local` | `http://127.0.0.1:8000` |
 
 Precedence: an explicit non-default **`server_url` wins over `env`**, which wins
 over the default. An unknown preset raises `ValueError`. `env` is also accepted
@@ -215,7 +217,12 @@ Create a new async client.
 
 | Method | Description |
 |--------|-------------|
-| `await remember(text, namespace?)` | Store a memory |
+| `await remember(text, namespace?)` | Accept a background remember job and return `job_id` |
+| `await wait_for_remember_job(job_id, ...)` | Poll one remember job until it is searchable |
+| `await remember_and_wait(text, namespace?, ...)` | Store a memory and wait until it is searchable |
+| `await remember_bulk(items)` | Accept several background remember jobs |
+| `await wait_for_remember_jobs(job_ids, opts?)` | Poll several remember jobs together |
+| `await remember_bulk_and_wait(items, opts?)` | Store several memories and wait for completion |
 | `await recall(RecallParams(query, limit?, namespace?, max_distance?))` | Search memories, optionally filtering by distance |
 | `await analyze(text, namespace?)` | Extract and store facts |
 | `await ask(question, limit?, namespace?)` | Ask a question answered using memories |

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/README.md

@@ -18,6 +18,10 @@ pip install memwal[openai]      # OpenAI SDK support
 pip install memwal[all]         # Everything
 ```
 
+## Try It In Colab
+
+Open the runnable [Walrus Memory Python SDK Colab](https://colab.research.google.com/drive/1SaKjkSp0DXnM_nktWSiEC-l9qGtVr6ph) for a notebook walkthrough covering installation, secure `staging` configuration, optional `prod`, health checks, `remember`, `remember_async`, async job waiting, `recall`, bulk remember, `remember_bulk_async`, `remember_bulk_and_wait`, optional SDK utilities, OpenAI/LangChain middleware, OpenAI-compatible provider settings such as `OPENAI_BASE_URL`, and troubleshooting.
+
 ## Quick Start
 
 Set your environment variables first:
@@ -45,8 +49,8 @@ async def main():
         server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
     )
 
-    # Store a memory
-    result = await memwal.remember("I'm allergic to peanuts")
+    # Store a memory and wait until the background job is searchable
+    result = await memwal.remember_and_wait("I'm allergic to peanuts")
     print(result.blob_id)
 
     # Recall memories
@@ -54,8 +58,8 @@ async def main():
     for memory in matches.results:
         print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
 
-    # Analyze conversation for facts
-    analysis = await memwal.analyze("I love coffee and live in Tokyo")
+    # Analyze conversation for facts and wait until extracted facts are searchable
+    analysis = await memwal.analyze_and_wait("I love coffee and live in Tokyo")
     for fact in analysis.facts:
         print(fact.text)
 
@@ -76,7 +80,7 @@ client = MemWalSync.create(
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
 )
 
-result = client.remember("I'm allergic to peanuts")
+result = client.remember_and_wait("I'm allergic to peanuts")
 matches = client.recall(RecallParams(query="food allergies"))
 client.close()
 ```
@@ -91,7 +95,7 @@ async with MemWal.create(
     key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
 ) as memwal:
-    await memwal.remember("I prefer dark mode")
+    await memwal.remember_and_wait("I prefer dark mode")
 ```
 
 ## Environment Presets
@@ -105,16 +109,14 @@ from memwal import MemWal
 memwal = MemWal.create(
     key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
-    env="prod",   # prod | dev | staging | local
+    env="staging",   # staging for testing, prod for production
 )
 ```
 
 | `env` | Relayer URL |
 |-------|-------------|
 | `prod` | `https://relayer.memwal.ai` |
-| `dev` | `https://relayer.dev.memwal.ai` |
 | `staging` | `https://relayer.staging.memwal.ai` |
-| `local` | `http://127.0.0.1:8000` |
 
 Precedence: an explicit non-default **`server_url` wins over `env`**, which wins
 over the default. An unknown preset raises `ValueError`. `env` is also accepted
@@ -176,7 +178,12 @@ Create a new async client.
 
 | Method | Description |
 |--------|-------------|
-| `await remember(text, namespace?)` | Store a memory |
+| `await remember(text, namespace?)` | Accept a background remember job and return `job_id` |
+| `await wait_for_remember_job(job_id, ...)` | Poll one remember job until it is searchable |
+| `await remember_and_wait(text, namespace?, ...)` | Store a memory and wait until it is searchable |
+| `await remember_bulk(items)` | Accept several background remember jobs |
+| `await wait_for_remember_jobs(job_ids, opts?)` | Poll several remember jobs together |
+| `await remember_bulk_and_wait(items, opts?)` | Store several memories and wait for completion |
 | `await recall(RecallParams(query, limit?, namespace?, max_distance?))` | Search memories, optionally filtering by distance |
 | `await analyze(text, namespace?)` | Extract and store facts |
 | `await ask(question, limit?, namespace?)` | Ask a question answered using memories |

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/examples/.env.example

@@ -1,10 +1,10 @@
 # Local server (default) or remote relayer
 MEMWAL_SERVER_URL=http://localhost:8000
 # Ed25519 delegate private key (64-hex). Get from Walrus Memory dashboard.
-MEMWAL_PRIVATE_KEY=21b423e72282dcc47805de48ef9130331b642667b7b2a5cd621767928205e360
+MEMWAL_PRIVATE_KEY=<your-ed25519-delegate-private-key-hex>
 # Optional: paste the dashboard delegate public key so verification can catch mismatches.
 MEMWAL_DELEGATE_PUBLIC_KEY=
 # Walrus Memory account object ID on Sui (the wallet's account)
-MEMWAL_ACCOUNT_ID=0x8a1121b8f95d79e68bd07efaf71689ce6fd832b369cdb1b2a943ec7beb822392
+MEMWAL_ACCOUNT_ID=0x-your-walrus-memory-account-id
 # Namespace for these test memories
 MEMWAL_NAMESPACE=python-sdk-example

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/memwal/__init__.py

@@ -13,13 +13,13 @@ Quick start::
     )
 
     # Async
-    result = await memwal.remember("I love coffee")
+    result = await memwal.remember_and_wait("I love coffee")
     matches = await memwal.recall(RecallParams(query="beverage preferences"))
 
     # Sync wrapper
     from memwal import MemWalSync
     client = MemWalSync.create(key="...", account_id="0x...")
-    result = client.remember("I love coffee")
+    result = client.remember_and_wait("I love coffee")
 """
 
 from .client import (
@@ -116,4 +116,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.4.dev0"
+__version__ = "0.1.4.dev1"

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/memwal/client.py

@@ -177,7 +177,11 @@ def _occurred_at_to_wire(
         # shorthand; `fromisoformat` only accepts it on Python 3.11+,
         # so we normalise to "+00:00" before parsing for 3.9/3.10
         # compatibility.
-        normalised = occurred_at.replace("Z", "+00:00", 1) if occurred_at.endswith("Z") else occurred_at
+        normalised = (
+            occurred_at.replace("Z", "+00:00", 1)
+            if occurred_at.endswith("Z")
+            else occurred_at
+        )
         try:
             parsed = datetime.fromisoformat(normalised)
         except ValueError as exc:
@@ -1251,6 +1255,12 @@ class MemWalSync:
         except RuntimeError:
             loop = None
 
+        # Reset the httpx client before every asyncio.run() path so it is
+        # recreated inside the loop that will use it. This matters in
+        # notebooks/Jupyter where the sync wrapper runs coroutines in worker
+        # threads with short-lived event loops.
+        self._inner._client = None
+
         if loop is not None and loop.is_running():
             # Already inside an event loop (e.g. Jupyter).
             # Create a new loop in a thread.
@@ -1259,12 +1269,6 @@ class MemWalSync:
             with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
                 return pool.submit(asyncio.run, coro).result()
         else:
-            # Reset the httpx client before each asyncio.run() so it is
-            # recreated fresh inside the new event loop.  Without this,
-            # reusing a MemWalSync instance across multiple calls raises
-            # "RuntimeError: Event loop is closed" because the client's
-            # transport is still bound to the previous (now-closed) loop.
-            self._inner._client = None
             return asyncio.run(coro)
 
     def remember(

{memwal-0.1.4.dev0 → memwal-0.1.4.dev1}/memwal/middleware.py

@@ -128,6 +128,22 @@ def _fire_and_forget(coro: Any) -> None:
         thread.start()
 
 
+def _run_blocking(coro_factory: Callable[[], Any]) -> Any:
+    """Run a coroutine factory from sync code, including notebooks."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop is not None and loop.is_running():
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(lambda: asyncio.run(coro_factory())).result()
+
+    return asyncio.run(coro_factory())
+
+
 # ============================================================
 # LangChain Integration
 # ============================================================
@@ -417,9 +433,12 @@ def _wrap_sync_openai(
     """Wrap a sync OpenAI client's chat.completions.create."""
     original_create = client.chat.completions.create
 
-    def patched_create(*args: Any, **kwargs: Any) -> Any:
-        import asyncio
+    def _run_memwal(coro_factory: Callable[[], Any]) -> Any:
+        # Keep httpx clients bound to the short-lived loop that uses them.
+        memwal._client = None
+        return _run_blocking(coro_factory)
 
+    def patched_create(*args: Any, **kwargs: Any) -> Any:
         messages = kwargs.get("messages") or (args[0] if args else None)
         if messages is None:
             return original_create(*args, **kwargs)
@@ -428,8 +447,8 @@ def _wrap_sync_openai(
         user_text = _find_last_user_message(messages)
         if user_text:
             try:
-                recall_result = asyncio.run(
-                    memwal.recall(user_text, max_memories, namespace)
+                recall_result = _run_memwal(
+                    lambda: memwal.recall(user_text, max_memories, namespace)
                 )
                 relevant = [
                     m for m in recall_result.results
@@ -450,13 +469,14 @@ def _wrap_sync_openai(
 
         # Fire-and-forget analyze
         if auto_save and user_text:
-            async def _analyze() -> None:
+            def _analyze() -> None:
                 try:
-                    await memwal.analyze(user_text, namespace)
+                    _run_memwal(lambda: memwal.analyze(user_text, namespace))
                 except Exception as e:
                     log(f"[Walrus Memory] Auto-save failed: {e}")
 
-            _fire_and_forget(_analyze())
+            thread = threading.Thread(target=_analyze, daemon=True)
+            thread.start()
 
         return result