Recipes

Common patterns and recipes for MemoClaw.

Store User Preference

CLI

memoclaw store "User prefers dark mode" \
  --importance 0.8 \
  --tags preferences,ui

from memoclaw import MemoClaw

client = MemoClaw()
client.store(
    "User prefers dark mode",
    importance=0.8,
    tags=["preferences", "ui"],
)

curl -X POST https://api.memoclaw.com/v1/store \
  -H "Content-Type: application/json" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE" \
  -d '{
    "content": "User prefers dark mode",
    "importance": 0.8,
    "metadata": { "tags": ["preferences", "ui"] }
  }'

Store After Correction

CLI

memoclaw store "Correction: The database connection uses port 5433, not 5432" \
  --importance 0.95 \
  --tags corrections

client.store(
    "Correction: The database connection uses port 5433, not 5432",
    importance=0.95,
    tags=["corrections"],
)

curl -X POST https://api.memoclaw.com/v1/store \
  -H "Content-Type: application/json" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE" \
  -d '{
    "content": "Correction: The database connection uses port 5433, not 5432",
    "importance": 0.95,
    "metadata": { "tags": ["corrections"] }
  }'

Recall Before Responding

CLI

memoclaw recall "user's theme preference"

memories = client.recall("user's theme preference")
if memories.memories:
    theme = memories.memories[0].content
    print(f"User prefers: {theme}")

curl -X POST https://api.memoclaw.com/v1/recall \
  -H "Content-Type: application/json" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE" \
  -d '{ "query": "user'\''s theme preference" }'

Filter by Namespace

CLI

memoclaw recall "database configuration" \
  --namespace project-api \
  --limit 10

memories = client.recall(
    "database configuration",
    namespace="project-api",
    limit=10,
)

curl -X POST https://api.memoclaw.com/v1/recall \
  -H "Content-Type: application/json" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE" \
  -d '{
    "query": "database configuration",
    "namespace": "project-api",
    "limit": 10
  }'

Batch Import

CLI

memoclaw store-batch \
  '{"content": "Uses PostgreSQL 15", "importance": 0.9}' \
  '{"content": "Deploys to Railway", "importance": 0.8}' \
  '{"content": "Team of 3 developers", "importance": 0.7}'

memories = [
    {"content": "Uses PostgreSQL 15", "importance": 0.9},
    {"content": "Deploys to Railway", "importance": 0.8},
    {"content": "Team of 3 developers", "importance": 0.7},
]

result = client.store_batch(memories)
print(f"Stored {result.count} memories")

curl -X POST https://api.memoclaw.com/v1/store/batch \
  -H "Content-Type: application/json" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE" \
  -d '{
    "memories": [
      { "content": "Uses PostgreSQL 15", "importance": 0.9 },
      { "content": "Deploys to Railway", "importance": 0.8 },
      { "content": "Team of 3 developers", "importance": 0.7 }
    ]
  }'

Extract Facts from Conversation

CLI

memoclaw ingest \
  --messages '[{"role":"user","content":"I prefer dark mode and use vim."},{"role":"assistant","content":"Got it!"},{"role":"user","content":"My timezone is PST."}]' \
  --auto-relate

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

curl -X POST https://api.memoclaw.com/v1/ingest \
  -H "Content-Type: application/json" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE" \
  -d '{
    "messages": [
      { "role": "user", "content": "I prefer dark mode and use vim." },
      { "role": "assistant", "content": "Got it!" },
      { "role": "user", "content": "My timezone is PST." }
    ],
    "auto_relate": true
  }'

Proactive Memory Suggestions

CLI

memoclaw suggested --category stale --limit 5

suggested = client.suggested(category="stale", limit=5)

for memory in suggested.memories:
    print(f"- {memory.content[:50]}... (importance: {memory.importance})")

curl "https://api.memoclaw.com/v1/suggested?category=stale&limit=5" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE"

Error Handling

CLI

# CLI exits with non-zero codes on errors
memoclaw delete some-id || echo "Delete failed"

from memoclaw import MemoClaw, NotFoundError, RateLimitError, ValidationError

try:
    client.delete("some-id")
except NotFoundError:
    print("Memory already deleted")
except RateLimitError:
    print("Rate limited - wait and retry")
except ValidationError as e:
    print(f"Validation error: {e.message}")

# Check HTTP status codes
# 404 = not found, 429 = rate limited, 422 = validation error
curl -s -o /dev/null -w "%{http_code}" \
  -X DELETE "https://api.memoclaw.com/v1/memories/some-id" \
  -H "x-wallet-auth: $WALLET:$TIMESTAMP:$SIGNATURE"