Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.memwal.ai/llms.txt

Use this file to discover all available pages before exploring further.

See also:

MemWal.create(...)

MemWal.create(
    key: str,
    account_id: str,
    server_url: str = "http://localhost:8000",
    namespace: str = "default",
    env: str | None = None,
) -> MemWal
MemWalSync.create(...) has the same signature and returns a synchronous wrapper.
ArgumentTypeRequiredDefaultNotes
keystrYesEd25519 delegate private key in hex
account_idstrYesMemWalAccount object ID on Sui
server_urlstrNohttp://localhost:8000Explicit relayer URL — wins over env
namespacestrNo"default"Default namespace for memory isolation
envstrNoPreset: prod / dev / staging / local. Unknown → ValueError
You may also build a MemWalConfig and call MemWal(config) directly; env resolution happens in MemWalConfig.__post_init__.

MemWal Methods

All methods are coroutines on MemWal; MemWalSync exposes the same names without await.

remember(text, namespace=None) -> RememberAcceptedResult

Submit one memory. Returns after the relayer accepts a background job; embedding, SEAL encryption, Walrus upload, and indexing continue asynchronously. remember_async is an alias.
RememberAcceptedResult(job_id: str, status: str)

remember_and_wait(text, namespace=None, poll_interval_ms=1500, timeout_ms=60_000) -> RememberResult

Submit one memory and poll until the job completes.
RememberResult(id: str, blob_id: str, owner: str, namespace: str)

wait_for_remember_job(job_id, poll_interval_ms=1500, timeout_ms=60_000) -> RememberResult

Poll a previously accepted job until done or failed. Raises MemWalRememberJobNotFound / MemWalRememberJobFailed / MemWalRememberJobTimeout.

remember_bulk_async(items) -> RememberBulkAcceptedResult

Submit up to 20 RememberBulkItem in one request. remember_bulk is an alias.
RememberBulkAcceptedResult(job_ids: list[str], total: int, status: str)

get_remember_bulk_status(job_ids) -> RememberBulkStatusResult

One RememberBulkStatusItem(job_id, status, blob_id?, error?) per requested job.

wait_for_remember_jobs(job_ids, opts=None) -> RememberBulkResult

Poll a batch until every job is terminal. opts is a RememberBulkOptions(poll_interval_ms=1500, timeout_ms=120_000).
RememberBulkResult(
    results: list[RememberBulkItemResult],  # preserves input order
    total: int, succeeded: int, failed: int, timed_out: int,
)

remember_bulk_and_wait(items, opts=None) -> RememberBulkResult

remember_bulk_async + wait_for_remember_jobs in one call.

recall(query, limit=10, namespace=None, max_distance=None) -> RecallResult

Search memories matching a natural-language query, scoped to owner + namespace. When max_distance is set, the client drops weak matches where distance >= max_distance.
RecallResult(
    results: list[RecallMemory],  # RecallMemory(blob_id, text, distance)
    total: int,
)
distance is cosine distance — lower is more similar.

analyze(text, namespace=None) -> AnalyzeResult

Extract memorable facts via an LLM and enqueue one background remember job per fact.
AnalyzeResult(
    facts: list[AnalyzedFact],  # AnalyzedFact(text, id, blob_id)
    fact_count: int,
    job_ids: list[str],
    status: str,
    owner: str,
)
AnalyzeResult.total is a backward-compat alias for fact_count. Use analyze_and_wait(text, namespace=None, opts=None) -> AnalyzeWaitResult to wait for every fact job to settle.

ask(question, limit=5, namespace=None) -> AskResult

Answer a question using your memories as context.
AskResult(
    answer: str,
    memories_used: int,
    memories: list[AskMemory],  # AskMemory(blob_id, text, distance)
)

restore(namespace, limit=50) -> RestoreResult

Rebuild missing indexed entries for one namespace from Walrus. Incremental.
RestoreResult(restored: int, skipped: int, total: int, namespace: str, owner: str)

health() -> HealthResult

Check relayer health. No authentication. Raises MemWalError on non-200.
HealthResult(
    status: str,
    version: str,
    relayer_version: str | None = None,
    api_version: str | None = None,
    min_supported_sdk: dict[str, str] | None = None,
)

compatibility() -> dict

Fetch and validate the relayer compatibility contract from /version. Protected SDK calls run this check before signing the first request and raise MemWalCompatibilityError when the SDK/relayer pair is unsupported.

get_public_key_hex() -> str

Hex-encoded public key for the current delegate key.

close() / context managers

await memwal.close() closes the underlying httpx client. MemWal supports async with; MemWalSync supports with.

Lower-level methods

MethodDescription
remember_manual(RememberManualOptions)Register a pre-uploaded blob with a pre-computed vector → RememberManualResult
recall_manual(RecallManualOptions)Search with a pre-computed query vector → RecallManualResult (blob_id + distance only)
embed(text)Embedding vector for text, no storage → EmbedResult(vector)
See Manual methods.

Middleware

from memwal import with_memwal_langchain, with_memwal_openai
Both wrap an existing LLM client with automatic recall + save and accept: key, account_id, server_url, namespace, env, max_memories (5), auto_save (True), min_relevance (0.3), debug (False). The alias withMemWal maps to with_memwal_langchain. See with_memwal.

Exceptions

from memwal import (
    MemWalError,
    MemWalRememberJobNotFound,
    MemWalRememberJobFailed,
    MemWalRememberJobTimeout,
)
Exception.statusMeaning
MemWalErrorBase class for all SDK errors
MemWalRememberJobNotFound404Job unknown or not owned by the caller
MemWalRememberJobFailed500Job reached terminal failed (.error)
MemWalRememberJobTimeout504Polling exceeded .timeout_ms

Utility Functions

from memwal import delegate_key_to_sui_address, delegate_key_to_public_key
FunctionDescription
delegate_key_to_sui_address(private_key_hex)Derive the 0x-prefixed Sui address — blake2b-256(0x00 ‖ pubkey)
delegate_key_to_public_key(private_key_hex)32-byte Ed25519 public key bytes

Authentication

Every request is signed with Ed25519 (PyNaCl). Canonical message:
{timestamp}.{method}.{path_and_query}.{body_sha256}.{nonce}.{account_id}
Signed requests send x-public-key, x-signature, x-timestamp, x-nonce (UUID v4), and x-account-id. Relayer-mode requests also send x-seal-session; manual-mode requests omit decrypt credentials. SDKs that omit x-nonce are rejected by the server with 426 Upgrade Required.