> ## 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.

# MCP Integration

> Use MemoClaw as an MCP server for Claude Desktop, Cursor, and other MCP-compatible tools.

# MCP Integration

MemoClaw provides an MCP (Model Context Protocol) server for seamless integration with Claude Desktop, Cursor, Windsurf, and any MCP-compatible application.

## Installation

<Steps>
  <Step title="Install via npm">
    ```bash theme={null}
    npm install -g memoclaw-mcp
    ```
  </Step>

  <Step title="Configure your wallet">
    Set your EVM private key with USDC on Base:

    ```bash theme={null}
    export MEMOCLAW_PRIVATE_KEY=0xYourPrivateKey
    ```

    <Note>
      Use a dedicated wallet with USDC for API payments. The free tier includes 100 calls per wallet.
    </Note>
  </Step>

  <Step title="Configure your MCP client">
    Add MemoClaw to your MCP configuration file.
  </Step>
</Steps>

## Client Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "memoclaw": {
      "command": "npx",
      "args": ["-y", "memoclaw-mcp"],
      "env": {
        "MEMOCLAW_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}
```

### Cursor

Add to MCP settings in Cursor preferences:

```json theme={null}
{
  "mcpServers": {
    "memoclaw": {
      "command": "npx",
      "args": ["-y", "memoclaw-mcp"],
      "env": {
        "MEMOCLAW_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}
```

### OpenClaw (via mcporter)

If you're running [OpenClaw](https://openclaw.ai), use mcporter to add MemoClaw:

```bash theme={null}
npm install -g memoclaw-mcp
mcporter add memoclaw --stdio "memoclaw-mcp" --env "MEMOCLAW_PRIVATE_KEY=0xYourPrivateKey"
```

Or use the auto-setup script from the [MemoClaw skill on ClawHub](https://clawhub.ai/anajuliabit/memoclaw):

```bash theme={null}
export MEMOCLAW_PRIVATE_KEY=0xYourPrivateKey
bash skills/memoclaw/scripts/setup.sh
```

Once configured, your agent can call MemoClaw directly:

```bash theme={null}
mcporter call memoclaw.memoclaw_store '{"content": "User prefers dark mode", "importance": 0.8}'
mcporter call memoclaw.memoclaw_recall '{"query": "UI preferences"}'
```

### Other MCP Clients

Any MCP-compatible client can use the server:

```bash theme={null}
npx -y memoclaw-mcp
```

## Available Tools

### Core

| Tool              | Description                                        | Key Parameters                                                        |
| ----------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| `memoclaw_init`   | Check configuration and connection status          | (none)                                                                |
| `memoclaw_store`  | Store a memory with semantic embeddings            | `content`, `importance`, `tags`, `namespace`, `memory_type`, `pinned` |
| `memoclaw_recall` | Semantic search — find memories by meaning         | `query`, `limit`, `min_similarity`, `tags`, `namespace`               |
| `memoclaw_search` | Keyword search — find memories by exact text match | `query`, `limit`, `namespace`, `tags`, `memory_type`                  |
| `memoclaw_get`    | Retrieve a single memory by ID                     | `id`                                                                  |
| `memoclaw_list`   | List stored memories with pagination               | `limit`, `offset`, `tags`, `namespace`, `memory_type`                 |
| `memoclaw_update` | Update a memory by ID (partial update)             | `id`, `content`, `importance`, `tags`, `memory_type`, `pinned`        |
| `memoclaw_delete` | Delete a memory by ID                              | `id`                                                                  |
| `memoclaw_status` | Check free tier remaining calls                    | (none)                                                                |
| `memoclaw_count`  | Count memories with optional filters               | `namespace`, `tags`, `agent_id`, `memory_type`                        |

### Bulk Operations

| Tool                   | Description                                   | Key Parameters                         |
| ---------------------- | --------------------------------------------- | -------------------------------------- |
| `memoclaw_bulk_store`  | Store multiple memories in one call (max 100) | `memories[]`, `session_id`, `agent_id` |
| `memoclaw_bulk_delete` | Delete multiple memories by IDs (max 100)     | `ids[]`                                |

### Intelligence

| Tool                   | Description                                                                 | Key Parameters                                   |
| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
| `memoclaw_ingest`      | Bulk-ingest conversations/text — auto-extracts facts with dedup & relations | `messages`, `text`, `namespace`, `auto_relate`   |
| `memoclaw_extract`     | Extract structured facts from conversation via LLM (no auto-relations)      | `messages`, `namespace`                          |
| `memoclaw_consolidate` | Merge similar/duplicate memories by clustering                              | `namespace`, `min_similarity`, `mode`, `dry_run` |
| `memoclaw_suggested`   | Get proactive memory suggestions (stale, fresh, hot, decaying)              | `limit`, `namespace`, `category`                 |

### Relations & Graph

| Tool                       | Description                                      | Key Parameters                                |
| -------------------------- | ------------------------------------------------ | --------------------------------------------- |
| `memoclaw_create_relation` | Create a relationship between two memories       | `memory_id`, `target_id`, `relation_type`     |
| `memoclaw_list_relations`  | List all relationships for a memory              | `memory_id`                                   |
| `memoclaw_delete_relation` | Delete a relationship                            | `memory_id`, `relation_id`                    |
| `memoclaw_graph`           | Traverse the memory graph from a starting memory | `memory_id`, `depth` (max 3), `relation_type` |

### Import & Export

| Tool               | Description                                 | Key Parameters                            |
| ------------------ | ------------------------------------------- | ----------------------------------------- |
| `memoclaw_export`  | Export all memories as JSON                 | `namespace`, `agent_id`, `format`         |
| `memoclaw_import`  | Import memories from a JSON array (max 100) | `memories[]`, `session_id`, `agent_id`    |
| `memoclaw_migrate` | Migrate markdown files into MemoClaw        | `path`, `files[]`, `namespace`, `dry_run` |

### Namespace Management

| Tool                        | Description                                      | Key Parameters          |
| --------------------------- | ------------------------------------------------ | ----------------------- |
| `memoclaw_delete_namespace` | Delete ALL memories in a namespace (destructive) | `namespace`, `agent_id` |

***

## Tool Details

### memoclaw\_init

Check if MemoClaw is properly configured. Call this first to verify the connection, wallet address, and free tier status.

```json theme={null}
{}
```

### memoclaw\_store

Store a new memory with semantic embeddings.

```json theme={null}
{
  "content": "User prefers dark mode and uses vim keybindings",
  "importance": 0.8,
  "tags": ["preferences", "editor"],
  "namespace": "default"
}
```

### memoclaw\_recall

Semantic search — find memories by meaning, not exact words.

```json theme={null}
{
  "query": "What are the user's editor preferences?",
  "limit": 5,
  "min_similarity": 0.7
}
```

### memoclaw\_search

Keyword search — find memories containing exact text (case-insensitive).

```json theme={null}
{
  "query": "python",
  "limit": 10,
  "namespace": "project-x"
}
```

### memoclaw\_get

Retrieve a single memory by its exact ID.

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### memoclaw\_list

List all stored memories with pagination.

```json theme={null}
{
  "limit": 20,
  "offset": 0,
  "tags": ["preferences"],
  "namespace": "default"
}
```

### memoclaw\_update

Update an existing memory. Only provided fields are changed.

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "importance": 0.9,
  "pinned": true
}
```

### memoclaw\_delete

Remove a memory by its ID.

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### memoclaw\_bulk\_store

Store multiple memories in a single call (max 100).

```json theme={null}
{
  "memories": [
    { "content": "Prefers TypeScript", "importance": 0.7, "tags": ["preferences"] },
    { "content": "Uses VS Code", "importance": 0.5, "tags": ["preferences"] }
  ]
}
```

### memoclaw\_bulk\_delete

Delete multiple memories at once (max 100 IDs).

```json theme={null}
{
  "ids": ["id-1", "id-2", "id-3"]
}
```

### memoclaw\_count

Get a count of memories with optional filters. Faster than `memoclaw_list` when you only need the total.

```json theme={null}
{
  "namespace": "project-x",
  "memory_type": "correction"
}
```

### memoclaw\_status

Check your free tier usage.

```json theme={null}
{}
```

Response:

```
Wallet: 0x...
Free tier: 87/100 calls remaining
```

### memoclaw\_ingest

Bulk-ingest a conversation or raw text. The server extracts facts, deduplicates, and optionally creates relations.

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "I switched from JavaScript to TypeScript last month" },
    { "role": "assistant", "content": "Got it! I'll remember your preference for TypeScript." }
  ],
  "auto_relate": true
}
```

### memoclaw\_extract

Extract structured facts from a conversation via LLM, without auto-relating them.

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "My project uses React with Tailwind CSS" }
  ]
}
```

### memoclaw\_consolidate

Merge similar/duplicate memories by clustering. Use `dry_run: true` first to preview.

```json theme={null}
{
  "namespace": "default",
  "dry_run": true
}
```

### memoclaw\_suggested

Get proactive memory suggestions: stale, fresh, hot, or decaying memories.

```json theme={null}
{
  "category": "stale",
  "limit": 5
}
```

### memoclaw\_create\_relation

Create a directed relationship between two memories.

```json theme={null}
{
  "memory_id": "source-id",
  "target_id": "target-id",
  "relation_type": "supersedes"
}
```

Relation types: `related_to`, `derived_from`, `contradicts`, `supersedes`, `supports`.

### memoclaw\_list\_relations

List all relationships for a memory (both incoming and outgoing).

```json theme={null}
{
  "memory_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### memoclaw\_delete\_relation

Delete a specific relationship.

```json theme={null}
{
  "memory_id": "source-id",
  "relation_id": "relation-id"
}
```

### memoclaw\_graph

Traverse the memory graph from a starting point.

```json theme={null}
{
  "memory_id": "550e8400-e29b-41d4-a716-446655440000",
  "depth": 2
}
```

### memoclaw\_export

Export all memories as JSON for backup or analysis.

```json theme={null}
{
  "namespace": "default",
  "format": "json"
}
```

### memoclaw\_import

Import memories from a JSON array (max 100 per call).

```json theme={null}
{
  "memories": [
    { "content": "Imported fact 1", "importance": 0.6 },
    { "content": "Imported fact 2", "tags": ["imported"] }
  ]
}
```

### memoclaw\_migrate

Migrate markdown files into MemoClaw. Use `dry_run: true` to preview.

```json theme={null}
{
  "path": "/home/user/.openclaw/workspace/memory/",
  "namespace": "migrated",
  "dry_run": true
}
```

### memoclaw\_delete\_namespace

Delete ALL memories in a namespace. **This is destructive and cannot be undone.** Use `memoclaw_count` first.

```json theme={null}
{
  "namespace": "old-project"
}
```

## Example Prompts

Once configured, you can ask Claude:

* "Remember that I prefer TypeScript over JavaScript"
* "What did I say about my coding preferences?"
* "List all memories tagged with 'project'"
* "Delete the memory about the old API key"

## Free Tier

The MCP server includes a free tier of **100 calls per wallet**. After exhausting the free tier, calls are paid via x402 protocol (USDC on Base).

## Environment Variables

| Variable               | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `MEMOCLAW_PRIVATE_KEY` | EVM private key for authentication and payments  |
| `MEMOCLAW_URL`         | API URL (defaults to `https://api.memoclaw.com`) |

## Troubleshooting

### "MEMOCLAW\_PRIVATE\_KEY environment variable required"

Make sure the environment variable is set in your MCP configuration or shell profile.

### "Wallet authentication failed"

Ensure your wallet has USDC on Base for paid calls, or check your free tier status.

### Connection issues

Restart your MCP client after changing configuration.

## Learn More

* [MCP Specification](https://modelcontextprotocol.io)
* [MemoClaw API Reference](/api-reference/overview)
* [x402 Protocol](https://x402.org)