> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install the official Python SDK and start storing memories in 3 lines.

## Installation

```bash theme={null}
pip install memoclaw
```

### Optional extras

```bash theme={null}
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.

```bash theme={null}
# 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

<Steps>
  <Step title="Store a memory">
    ```python theme={null}
    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)
    ```
  </Step>

  <Step title="Recall memories">
    ```python theme={null}
    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
    ```
  </Step>

  <Step title="Update and delete">
    ```python theme={null}
    # Update importance
    client.update(result.id, importance=0.95)

    # Delete when no longer needed
    client.delete(result.id)
    ```
  </Step>
</Steps>

## Async Support

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore all available endpoints.
  </Card>

  <Card title="Authentication" icon="lock" href="/get-started/authentication">
    Learn how x402 payment-as-identity works.
  </Card>
</CardGroup>