Walrus Memory Python SDK

Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing.

All data processing (encryption, embedding, Walrus storage) happens server-side in a TEE. The SDK signs requests with your Ed25519 delegate key and sends text over HTTPS.

Installation

pip install memwal

With optional integrations:

pip install memwal[langchain]   # LangChain support
pip install memwal[openai]      # OpenAI SDK support
pip install memwal[all]         # Everything

Try It In Colab

Open the runnable Walrus Memory Python SDK Colab 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:

export MEMWAL_PRIVATE_KEY="your-ed25519-delegate-private-key-hex"
export MEMWAL_ACCOUNT_ID="0x-your-walrus-memory-account-id"
export MEMWAL_SERVER_URL="https://relayer.memory.walrus.xyz"

MEMWAL_PRIVATE_KEY is the delegate private key from the Walrus Memory dashboard and must stay server-side.

Async (recommended)

import asyncio
import os
from memwal import MemWal, RecallParams

async def main():
    memwal = MemWal.create(
        key=os.environ["MEMWAL_PRIVATE_KEY"],
        account_id=os.environ["MEMWAL_ACCOUNT_ID"],
        server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memory.walrus.xyz"),
    )

    # 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
    matches = await memwal.recall(RecallParams(query="food allergies", limit=10, max_distance=0.8))
    for memory in matches.results:
        print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")

    # 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)

    await memwal.close()

asyncio.run(main())

0.8 is a starting point for the distance cutoff. Calibrate max_distance against your own memories and query phrasing: lower values reduce noise, while higher values preserve more relevant matches.

Sync

import os
from memwal import MemWalSync, RecallParams

client = MemWalSync.create(
    key=os.environ["MEMWAL_PRIVATE_KEY"],
    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
    server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memory.walrus.xyz"),
)

result = client.remember_and_wait("I'm allergic to peanuts")
matches = client.recall(RecallParams(query="food allergies"))
client.close()

Offline tests and CI

MemWalMock and MemWalMockSync implement the common memory API in process. They require no credentials, relayer, chain, or paid storage and use deterministic token-overlap ranking.

from memwal import MemWalMock, RecallParams

async def test_memory_flow():
    memwal = MemWalMock.create(namespace="test-user")
    await memwal.remember_and_wait("The user prefers dark mode")

    result = await memwal.recall(RecallParams(query="display preference"))
    assert "dark mode" in result.results[0].text

The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, list_namespaces, forget(blob_id), and clear(namespace). For deterministic behavior, analyze stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.

Context Manager

import os
from memwal import MemWal

async with MemWal.create(
    key=os.environ["MEMWAL_PRIVATE_KEY"],
    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
) as memwal:
    await memwal.remember_and_wait("I prefer dark mode")

Environment Presets

Instead of hardcoding a relayer URL, pass env to target a hosted relayer. Same shorthand as the TypeScript SDK and MCP package.

from memwal import MemWal

memwal = MemWal.create(
    key=os.environ["MEMWAL_PRIVATE_KEY"],
    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
    env="staging",   # staging for testing, prod for production
)

Precedence: any explicit server_url wins over env, including the hosted default. env applies only when server_url is omitted (None). An unknown preset raises ValueError. env is also accepted by MemWalSync.create, with_memwal_langchain, and with_memwal_openai.

AI Middleware

LangChain

import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from memwal import with_memwal_langchain

llm = ChatOpenAI(model="gpt-4o")
smart_llm = with_memwal_langchain(
    llm,
    key=os.environ["MEMWAL_PRIVATE_KEY"],
    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
    server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memory.walrus.xyz"),
    max_memories=5,
    min_relevance=0.3,
)

# Memories are automatically recalled and injected
response = await smart_llm.ainvoke([HumanMessage("What are my food allergies?")])

OpenAI SDK

import os
from openai import AsyncOpenAI
from memwal import with_memwal_openai

client = AsyncOpenAI()
smart_client = with_memwal_openai(
    client,
    key=os.environ["MEMWAL_PRIVATE_KEY"],
    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
    server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memory.walrus.xyz"),
)

# Memories are automatically recalled and injected
response = await smart_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What are my food allergies?"}],
)

API Reference

MemWal.create(key, account_id, server_url?, namespace?)

Create a new async client.

Methods

Authentication

Every request is signed with Ed25519:

message = f"{timestamp}.{method}.{path_and_query}.{body_sha256}.{nonce}.{account_id}"

Signed requests send x-public-key, x-signature, x-timestamp, x-nonce, and x-account-id. Relayer-mode requests also send x-seal-session; manual-mode requests omit decrypt credentials.

License

MIT