Skip to content
dongowu
memwal
Public

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
examples
examples
 
 
memwal
memwal
 
 
move
move
 
 
tests
tests
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

MemWal — Walrus-Powered Memory for AI Agents

One line to give any AI agent persistent, cross-session, verifiable memory on Sui.

Sui Overflow 2026 — Walrus Track Submission
pip install memwal → from memwal import MemWalMemory

The Problem

AI agents today are stateless. They lose context across sessions, can't share knowledge with other agents, and have no way to prove what they remembered or when. Memory is locked inside proprietary platforms.

MemWal fixes this. Walrus decentralized storage + Sui on-chain references = verifiable, composable, persistent agent memory that any framework can adopt.

Architecture

flowchart LR
    subgraph Agents["AI AGENTS"]
        direction TB
        A1["Research Agent\n(Python, LLM)"]
        A2["Risk Agent\n(Python)"]
        A3["Trader Agent\n(LangChain)"]
    end

    subgraph MemWal["MEMWAL SDK"]
        direction TB
        MW1["MemWalMemory\n— save / read / query"]
        MW2["LangChainMemWal\n— LangChain adapter"]
        MW3["WalrusClient\n— HTTP blob store"]
    end

    subgraph Sui["SUI + WALRUS"]
        direction TB
        W["Walrus\n— decentralized blob storage"]
        M["agent_memory.move\n— on-chain blob references"]
        S["Seal\n— optional encryption"]
    end

    Agents -- "memory.save() / memory.query()" --> MemWal
    MemWal -- "store / read blobs" --> W
    MemWal -- "mint MemoryObject" --> M
    MemWal -. "encrypt" .-> S
Loading

Quick Start

pip install memwal
from memwal import MemWalMemory, MemoryQuery

# One line setup
mem = MemWalMemory(namespace="my-agent")

# Agent saves memory → stored on Walrus, referenced on-chain
blob_id = mem.save(
    agent_id="analyst-1",
    content={"signal": "BUY", "token": "SUI", "confidence": 0.88},
    tags=["research", "signal"],
)

# Another agent (same namespace) queries shared memory
entries = mem.query(MemoryQuery(tags=["research"], limit=5))
for e in entries:
    print(f"[{e.agent_id}] {e.content['signal']} — {e.content['reason']}")

# Read full context from a specific blob
entry = mem.read(blob_id)

# Persist index for next session
index_blob = mem.save_index()

# Next session: restore
mem.load_index(index_blob)

CLI

# Store data
memwal store --text "buy signal for SUI"
# → blob_id: ABC123...

# Read data
memwal read ABC123...

# Agent memory
memwal memory --agent-id trader-1 --namespace defi --save '{"action":"buy","token":"SUI"}'
memwal memory --agent-id trader-1 --namespace defi --query

LangChain

from memwal.integrations.langchain import LangChainMemWal

memory = LangChainMemWal(agent_id="chatbot-1", namespace="support")

# Use like any LangChain memory
agent = create_agent(llm, tools, memory=memory)
# Agent now has persistent, cross-session, cross-agent memory on Walrus

Walrus Track Requirements

Requirement Implementation
Persistent data via Walrus WalrusClient.store() / read() — direct HTTP blob store
Long-running workflows MemWalMemory.save_index() / load_index() — survive restarts
Multi-agent collaboration Shared namespace — multiple agents read/write same memory space
Artifact-driven workflow Reports, signals, decisions stored as JSON blobs, retrieved by subsequent agents
Move MemoryObject on-chain agent_memory.move — verifiable, timestamped blob references on Sui
Developer tooling Python SDK + CLI + LangChain adapter + examples
Optional Seal privacy MemoryObjectClient supports Seal-encrypted blobs

Examples

Example Description
examples/basic_usage.py Store, read, query, stats, index persistence
examples/multi_agent.py Research → Risk → Trader multi-agent collaboration
examples/langchain_demo.py LangChainMemWal as drop-in conversation memory 
python examples/basic_usage.py
python examples/multi_agent.py
python examples/langchain_demo.py

Project Structure

memwal/
├── pyproject.toml                  # Package config (pip install memwal)
├── memwal/
│   ├── __init__.py                 # Public API exports
│   ├── client.py                   # Walrus HTTP client (store / read)
│   ├── memory.py                   # Core memory layer (MemWalMemory)
│   ├── memory_object.py            # Sui Move MemoryObject client
│   ├── cli.py                      # CLI tool (memwal store/read/memory)
│   └── integrations/
│       ├── __init__.py
│       └── langchain.py            # LangChain BaseMemory adapter
├── move/
│   ├── Move.toml
│   └── sources/
│       └── agent_memory.move       # On-chain MemoryObject (Sui Move)
├── examples/
│   ├── basic_usage.py
│   ├── multi_agent.py
│   └── langchain_demo.py
└── tests/
    ├── conftest.py
    └── test_client.py

API Reference

WalrusClient

Method Description
store(data: bytes) -> blob_id Store raw bytes on Walrus
store_json(obj: dict) -> blob_id Store JSON-serializable dict
read(blob_id: str) -> bytes Read raw bytes from Walrus
read_json(blob_id: str) -> dict Read and parse JSON blob
blob_url(blob_id: str) -> str Get public aggregator URL
health() -> dict Connectivity check

MemWalMemory

Method Description
save(agent_id, content, *, namespace, tags, metadata) -> blob_id Save agent memory entry
read(blob_id: str) -> MemoryEntry Read and parse a memory entry
query(MemoryQuery) -> list[MemoryEntry] Filter entries by agent, namespace, tags, time
share(blob_id, target_agent_id) -> MemoryEntry Share entry with another agent
save_index() -> blob_id Persist in-memory index to Walrus
load_index(blob_id) -> int Restore index from Walrus
stats() -> dict Entry/namespace/agent counts

MemoryQuery

Field Description
namespace Filter by namespace
agent_id Filter by agent
tags Filter by tags (any match)
since ISO timestamp filter
limit Max results (default 20)

Deploying the Move Contract

cd move
sui move build
sui client publish --gas-budget 100000000
# Save the package ID → pass to MemoryObjectClient(package_id=...)

Comparison

Feature LangChain Memory OpenAI Memory MemWal
Persists across sessions In-memory (or vendor DB) Platform-bound Decentralized (Walrus)
Multi-agent sharing No No Yes (shared namespace)
On-chain verifiable No No Yes (MemoryObject)
No vendor lock-in Varies No Open protocol
Framework agnostic LangChain only OpenAI only Any agent (HTTP SDK)

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages