memwal-checkpoint 0.1.1__tar.gz

memwal_checkpoint-0.1.1/.env.example

@@ -0,0 +1,37 @@
+# Your Sui wallet private key (base64 or hex-encoded Ed25519 key).
+SUI_PRIVATE_KEY=your_base64_or_hex_private_key_here
+
+# Sui Move package ID for the MemWal registry contract.
+# Set this after deploying the contract.
+REGISTRY_PACKAGE_ID=0x0000000000000000000000000000000000000000000000000000000000000000
+
+# Shared object ID of the deployed CheckpointRegistry.
+# Set this after deploying the contract.
+REGISTRY_OBJECT_ID=0x0000000000000000000000000000000000000000000000000000000000000000
+
+# Optional (defaults target Sui / Walrus testnet)
+
+# Sui full-node JSON-RPC endpoint.
+# SUI_RPC_URL=https://fullnode.testnet.sui.io:443
+
+# Walrus publisher (blob store) endpoint.
+# WALRUS_PUBLISHER=https://publisher.walrus-testnet.walrus.space
+
+# Walrus aggregator (blob read) endpoint.
+# WALRUS_AGGREGATOR=https://aggregator.walrus-testnet.walrus.space
+
+# Number of Walrus storage epochs to request when storing a blob.
+# STORAGE_EPOCHS=5
+
+# Set to 1 for verbose Sui RPC debug output.
+MEMWAL_DEBUG=0
+
+# Checkpoint storage strategy: snapshot or delta.
+# CHECKPOINT_STRATEGY=snapshot
+
+# Snapshot frequency for snapshot mode.
+# SNAPSHOT_EVERY_N=5
+
+# Optional LLM Provider
+
+# OPENAI_API_KEY=your_openai_api_key_here

memwal_checkpoint-0.1.1/.gitattributes

@@ -0,0 +1,9 @@
+* text=auto
+*.py text eol=lf
+*.move text eol=lf
+*.toml text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+*.js text eol=lf

memwal_checkpoint-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then
+            pip install -r requirements.txt
+          fi
+          if [ -f requirements-dev.txt ]; then
+            pip install -r requirements-dev.txt
+          fi
+          if [ -f pyproject.toml ] && grep -q "pytest" pyproject.toml; then
+            pip install ".[dev]"
+          fi
+
+      - name: Python compile check
+        shell: bash
+        run: |
+          set -euo pipefail
+          files=()
+          for file in memwal/*.py agents/demo.py api/index.py playground/server.py; do
+            if [ -e "$file" ]; then
+              files+=("$file")
+            fi
+          done
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No Python files found for compile check."
+            echo "✓ Python compile check"
+          else
+            if python -m py_compile "${files[@]}"; then
+              echo "✓ Python compile check"
+            else
+              echo "✗ Compile failed"
+              echo "CI FAILED"
+              exit 1
+            fi
+          fi
+
+      - name: Smoke test
+        shell: bash
+        run: |
+          set -euo pipefail
+          if python - <<'PY'
+          from memwal.checkpoint import WalrusCheckpointer
+          from memwal.walrus import WalrusClient
+          from memwal.sui import SuiRegistry
+
+          print("MemWal smoke test passed")
+          PY
+          then
+            echo "✓ Smoke test"
+          else
+            echo "✗ Smoke test failed"
+            echo "CI FAILED"
+            exit 1
+          fi
+
+      - name: Pytest
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ ! -d tests ]; then
+            echo "No tests directory found."
+            echo "Skipping pytest."
+            echo "✓ Pytest"
+            exit 0
+          fi
+
+          if [ "${MEMWAL_RUN_LIVE_TESTS:-0}" != "1" ]; then
+            echo "Live integration tests are present, but MEMWAL_RUN_LIVE_TESTS is not set to 1."
+            echo "Skipping pytest to avoid live Walrus/Sui network calls and writes."
+            echo "✓ Pytest"
+            exit 0
+          fi
+
+          if pytest tests/ -v; then
+            echo "✓ Pytest"
+          else
+            echo "✗ Pytest failed"
+            echo "CI FAILED"
+            exit 1
+          fi
+
+      - name: CI result
+        shell: bash
+        run: |
+          echo "CI PASSED"

memwal_checkpoint-0.1.1/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+*.sqlite3
+
+# Virtual environments
+.venv/
+venv/
+env/
+audit-env/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Node.js
+node_modules/
+package-lock.json
+yarn.lock
+
+# Local editor/OS files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Vercel local state
+.vercel/
+
+# Sui Move build output
+contracts/build/
+
+# Sui keystore / wallet (never commit private keys)
+*.keystore
+sui.keystore
+
+# Logs
+*.log

memwal_checkpoint-0.1.1/.vercelignore

@@ -0,0 +1,14 @@
+.env
+.env.*
+!.env.example
+.git/
+.pytest_cache/
+.venv/
+__pycache__/
+contracts/build/
+dist/
+build/
+*.pyc
+*.pyo
+*.log
+

memwal_checkpoint-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surojit Guha
+
+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.

memwal_checkpoint-0.1.1/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: memwal-checkpoint
+Version: 0.1.1
+Summary: Portable memory for AI agents using Walrus and Sui.
+Project-URL: Homepage, https://github.com/Surojit012/memwal
+Project-URL: Repository, https://github.com/Surojit012/memwal
+Author: Surojit Guha
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core>=0.2.38
+Requires-Dist: langgraph-checkpoint>=2.0
+Requires-Dist: langgraph>=0.2
+Requires-Dist: msgpack>=1.0
+Requires-Dist: nest-asyncio>=1.6
+Requires-Dist: pynacl>=1.5
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: langchain-anthropic>=0.3; extra == 'llm'
+Provides-Extra: playground
+Requires-Dist: fastapi>=0.115; extra == 'playground'
+Requires-Dist: python-multipart>=0.0.9; extra == 'playground'
+Requires-Dist: uvicorn>=0.30; extra == 'playground'
+Description-Content-Type: text/markdown
+
+# 🧠 MemWal
+
+> Portable memory for AI agents.
+
+A decentralized LangGraph checkpoint backend powered by Walrus and Sui.
+
+**Kill the machine. Start another one. The agent continues.**
+
+![Python](https://img.shields.io/badge/Python-3.10+-blue)
+![LangGraph](https://img.shields.io/badge/LangGraph-Supported-green)
+![Sui + Walrus](https://img.shields.io/badge/Sui+Walrus-Testnet-purple)
+
+## 🚀 TL;DR
+
+```text
+Today:
+
+AI Agent
+
+↓
+
+Local RAM
+
+↓
+
+Process dies
+
+↓
+
+Memory lost
+
+
+With MemWal:
+
+AI Agent
+
+↓
+
+Walrus
+
+↓
+
+Sui
+
+↓
+
+Resume anywhere
+```
+
+MemWal lets LangGraph agents survive machine restarts without relying on SQLite, Redis, or local files.
+
+## Why MemWal?
+
+Most AI agent memory is tied to the machine where the agent is running. If the process exits, the container restarts, or the developer switches machines, the agent's state often disappears with it unless a local database or custom persistence layer has been wired in.
+
+Without MemWal:
+
+```text
+AI Agent
+
+↓
+
+Local RAM
+
+↓
+
+Machine dies
+
+↓
+
+Memory lost
+```
+
+With MemWal:
+
+```text
+AI Agent
+
+↓
+
+Walrus
+
+↓
+
+Sui
+
+↓
+
+Memory survives
+```
+
+MemWal replaces local-only checkpoint storage with decentralized persistence while keeping the LangGraph developer experience familiar.
+
+## Architecture
+
+```text
+LangGraph Agent
+
+↓
+
+WalrusCheckpointer
+
+↓
+
+Walrus (blob storage)
+
+↓
+
+Sui (thread_id → blob_id registry)
+
+↓
+
+Resume anywhere
+```
+
+At a high level, MemWal stores checkpoint bytes in Walrus and records the latest blob ID for each `thread_id` in a Sui registry object.
+
+## ✅ What We Verified
+
+| Capability             | Status |
+| ---------------------- | ------ |
+| Snapshot checkpoints   | ✅      |
+| Delta checkpoints      | ✅      |
+| Cross-machine recovery | ✅      |
+| Multi-thread isolation | ✅      |
+| Storage benchmarks     | ✅      |
+| Walrus integration     | ✅      |
+| Sui integration        | ✅      |
+| GitHub CI              | ✅      |
+
+## 🌍 Why this matters
+
+Today's agent memory is usually tied to:
+
+* RAM
+* SQLite
+* Redis
+* Local files
+
+If the machine disappears, the memory disappears.
+
+MemWal decouples memory from compute.
+
+An agent can stop running on one machine and continue running on another by restoring its state from Walrus and Sui.
+
+## Features
+
+* Snapshot checkpoints
+* Delta checkpoints
+* Cross-machine recovery
+* Multi-thread isolation
+* On-chain thread registry
+* Storage benchmarks
+* GitHub CI
+
+## Installation
+
+```bash
+pip install memwal-checkpoint
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/Surojit012/memwal.git
+```
+
+> **Note**
+>
+> MemWal is the product name.
+>
+> `memwal-checkpoint` is the Python package distribution name.
+>
+> Imports remain:
+>
+> ```python
+> from memwal import WalrusCheckpointer
+> ```
+
+## 🛠️ Development
+
+Install local development dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Install the package:
+
+```bash
+pip install -e .
+```
+
+## ⚡ One-line integration
+
+Replace:
+
+```python
+checkpointer = MemorySaver()
+```
+
+with:
+
+```python
+checkpointer = WalrusCheckpointer.from_env()
+```
+
+That's it.
+
+Your LangGraph agent now stores memory on Walrus and uses Sui as a decentralized thread registry.
+
+## Quickstart
+
+```python
+from memwal import WalrusCheckpointer
+
+checkpointer = WalrusCheckpointer.from_env()
+
+graph = builder.compile(
+    checkpointer=checkpointer
+)
+```
+
+## Live Demo Results
+
+The demo runner verifies MemWal against live Walrus and Sui testnet infrastructure.
+
+5 steps:
+
+| strategy | savings |
+| -------- | ------- |
+| snapshot | 60.87%  |
+| delta    | 53.75%  |
+
+20 steps:
+
+| strategy | savings |
+| -------- | ------- |
+| snapshot | 75.66%  |
+| delta    | 81.01%  |
+
+Delta mode becomes more efficient as conversations grow because it stores incremental changes instead of repeatedly uploading the full growing checkpoint.
+
+## Cross-machine verification
+
+MemWal has been verified with a cross-machine recovery flow:
+
+```text
+Machine A
+
+↓
+
+Store memory
+
+↓
+
+Destroy machine
+
+↓
+
+Machine B
+
+↓
+
+Restore memory
+```
+
+The restored agent state comes from Walrus and Sui, not from local files, local RAM, or a local database.
+
+## Multi-thread isolation
+
+MemWal has also been verified with independent thread recovery:
+
+```text
+Thread A -> Pizza
+
+Thread B -> Football
+
+Thread C -> Python
+```
+
+Each thread restores only its own memory. No cross-thread contamination was observed.
+
+## How it works
+
+1. Serialize the LangGraph checkpoint.
+2. Upload the checkpoint bytes to Walrus.
+3. Register the returned Walrus blob ID on Sui under the LangGraph `thread_id`.
+4. Restore by looking up the `thread_id` on Sui, fetching the blob from Walrus, and reconstructing the checkpoint.
+
+This gives each LangGraph thread a decentralized memory pointer:
+
+```text
+thread_id -> Sui registry -> Walrus blob -> LangGraph checkpoint
+```
+
+## 🎯 Demo Proof
+
+MemWal has been validated end-to-end on live Walrus and Sui testnet infrastructure.
+
+Verified scenarios:
+
+- ✅ Agent persistence
+- ✅ Cross-machine recovery
+- ✅ Multi-thread isolation
+- ✅ Snapshot checkpoints
+- ✅ Delta checkpoints
+- ✅ GitHub CI
+
+No local database was used.
+
+No local files were used.
+
+No in-memory state was reused.
+
+## Roadmap
+
+* Delta compaction
+* PyPI release
+* Monitoring dashboard
+
+## License
+
+MIT
+
+Kill the machine. Start another one. The agent continues.