Python SDK

Installation

pip install memoclaw

Optional extras

pip install "memoclaw[x402]"            # automatic x402 payments after free tier
pip install "memoclaw[langchain]"       # LangChain integration
pip install "memoclaw[llamaindex]"      # LlamaIndex integration
pip install "memoclaw[x402,langchain,llamaindex]"  # all extras

Authentication

MemoClaw uses Ethereum wallet signatures for auth. Any private key works — no ETH balance needed for the free tier.

# Generate a new key (one-time)
python -c "from eth_account import Account; a = Account.create(); print(f'MEMOCLAW_PRIVATE_KEY={a.key.hex()}')"

# Set the env var
export MEMOCLAW_PRIVATE_KEY=0x...

Every wallet gets 100 free API calls.

Quick Example

Store a memory

from memoclaw import MemoClaw

client = MemoClaw()  # uses MEMOCLAW_PRIVATE_KEY env var

result = client.store(
    "User prefers dark mode and vim keybindings",
    importance=0.8,
    tags=["preferences", "editor"],
)
print(result.id)

Recall memories

memories = client.recall("editor preferences", limit=5)
for m in memories.memories:
    print(f"[{m.similarity:.0%}] {m.content}")

Output:

[87%] User prefers dark mode and vim keybindings

Update and delete

# Update importance
client.update(result.id, importance=0.95)

# Delete when no longer needed
client.delete(result.id)

Async Support

from memoclaw import AsyncMemoClaw

async def main():
    async with AsyncMemoClaw() as client:
        result = await client.store("Async memory", importance=0.7)
        memories = await client.recall("async")
        print(memories.memories)

Ingest a Conversation

Extract facts automatically from conversation history:

result = client.ingest(
    messages=[
        {"role": "user", "content": "I prefer dark mode and use vim. My timezone is PST."},
        {"role": "assistant", "content": "Got it! I'll remember those preferences."},
    ],
    auto_relate=True,
)
print(f"Extracted {result.facts_extracted} facts, created {result.relations_created} relations")

Error Handling

from memoclaw import MemoClaw, NotFoundError, RateLimitError

client = MemoClaw()

try:
    client.delete("nonexistent-id")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited: {e.message}")

All Methods

Core

Method	Description
`store(content, **kwargs)`	Store a single memory
`store_batch(memories)`	Store up to 100 memories
`store_builder()`	Fluent builder for memory creation
`recall(query, **kwargs)`	Semantic search
`text_search(query, **kwargs)`	Free keyword text search (no embeddings)
`get(memory_id)`	Retrieve a single memory by ID
`list(**kwargs)`	List memories with pagination
`iter_memories(**kwargs)`	Iterator with auto-pagination
`update(memory_id, **kwargs)`	Update a memory
`update_batch(updates)`	Update up to 100 memories in batch
`delete(memory_id)`	Delete a memory
`delete_batch(ids)`	Delete multiple memories by ID
`status()`	Check free tier remaining calls

Intelligence

Method	Description
`ingest(**kwargs)`	Auto-extract facts from conversation
`extract(messages, **kwargs)`	Extract structured facts via LLM
`consolidate(**kwargs)`	Merge similar memories
`assemble_context(query, **kwargs)`	Assemble context block for LLM prompts
`suggested(**kwargs)`	Get proactive memory suggestions

Relations & Graph

Method	Description
`create_relation(...)`	Create a relationship
`list_relations(memory_id)`	List relationships
`delete_relation(...)`	Delete a relationship
`find_related(memory_id, **kwargs)`	Find filtered relations
`get_memory_graph(memory_id, depth)`	Traverse the memory graph

Import, Export & Management

Method	Description
`migrate(files, **kwargs)`	Bulk import markdown files
`export(**kwargs)`	Export memories (JSON/CSV/Markdown)
`get_history(memory_id)`	Get change history for a memory
`core_memories(**kwargs)`	Get high-importance/pinned memories
`list_namespaces()`	List namespaces with counts
`stats()`	Get memory usage statistics

Configuration

client = MemoClaw(
    private_key="0x...",               # or MEMOCLAW_PRIVATE_KEY env var
    base_url="http://localhost:3000",   # for local development
    timeout=60.0,                       # request timeout in seconds
)

Get Started

Concepts

Guides

Integrations

Reference

Installation

Optional extras

Authentication

Quick Example

Async Support

Ingest a Conversation

Error Handling

All Methods

Core

Intelligence

Relations & Graph

Import, Export & Management

Configuration

Next Steps

API Reference

Authentication

​Installation

​Optional extras

​Authentication

​Quick Example

​Async Support

​Ingest a Conversation

​Error Handling

​All Methods

​Core

​Intelligence

​Relations & Graph

​Import, Export & Management

​Configuration

​Next Steps

API Reference

Authentication

Installation

Optional extras

Authentication

Quick Example

Async Support

Ingest a Conversation

Error Handling

All Methods

Core

Intelligence

Relations & Graph

Import, Export & Management

Configuration

Next Steps