Skip to main content

​
Installation

pip install memoclaw
To enable automatic x402 payments when the free tier is exhausted: 
pip install "memoclaw[x402]"

​
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

1

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

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
3

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

MethodDescription
store(content, **kwargs)Store a single memory
store_batch(memories)Store up to 100 memories
recall(query, **kwargs)Semantic search
list(**kwargs)List memories with pagination
update(memory_id, **kwargs)Update a memory
delete(memory_id)Delete a memory
ingest(**kwargs)Auto-extract facts from conversation
extract(messages, **kwargs)Extract structured facts via LLM
consolidate(**kwargs)Merge similar memories
suggested(**kwargs)Get proactive memory suggestions
create_relation(...)Create a relationship
list_relations(memory_id)List relationships
delete_relation(...)Delete a relationship
status()Check free tier remaining calls

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

​
Next Steps

API Reference

Explore all available endpoints.

Authentication

Learn how x402 payment-as-identity works.