# Human-like Memory REST API Integration

Canonical website: https://plugin.human-like.me

Use the REST API when you want to integrate Human-like Memory into your own application, backend service, or agent runtime.

## Base URL

```text
https://plugin.human-like.me
```

## Authentication

All API requests require an API key passed through the `x-api-key` request header. Create an API key in the Dashboard under `API Keys`.

Required headers:

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | Use `application/json`. |
| `x-api-key` | Yes | Your API key. It starts with `mp_`. |
| `x-request-id` | No | Optional custom request ID for tracing. One is generated if omitted. |

Example:

```text
Content-Type: application/json
x-api-key: YOUR_API_KEY
```

## Available Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/plugin/v1/search/memory` | Search for relevant memories by natural language query. |
| `POST` | `/api/plugin/v1/add/message` | Add memories extracted from conversation messages. |

## Search Memory

Search for relevant memories based on a natural language query. Use this before generating an AI response to provide relevant context.

```text
POST /api/plugin/v1/search/memory
```

### Request Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes | - | Natural language query or search keywords. |
| `user_id` | string | No | - | User identifier for memory isolation. |
| `tags` | string[] | No | `null` | Filter results by tags. The OpenClaw plugin defaults to `["openclaw"]`. |
| `source` | string | No | `"openclaw"` | Source identifier. The plugin does not send this field; the server defaults to `openclaw`. |
| `memory_limit_number` | integer | No | `6` | Maximum number of memories to return. |
| `min_score` | float | No | `0.1` | Minimum relevance score from 0 to 1. Lower values usually return more results. |

### cURL Example

```bash
curl -X POST https://plugin.human-like.me/api/plugin/v1/search/memory \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "What does the user prefer?",
    "user_id": "user_001",
    "memory_limit_number": 5,
    "min_score": 0.1
  }'
```

### Python Example

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://plugin.human-like.me"

response = requests.post(
    f"{BASE_URL}/api/plugin/v1/search/memory",
    headers={
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "query": "What does the user prefer?",
        "user_id": "user_001",
        "memory_limit_number": 5,
        "min_score": 0.1,
    },
)

data = response.json()
if data["success"]:
    for mem in data["memories"]:
        print(f"[{mem['score']:.2f}] {mem['description']}")
else:
    print(f"Error: {data.get('error')}")
```

### Response Example

```json
{
  "success": true,
  "memories": [
    {
      "id": "mem_abc123",
      "conversation_id": "conv_001",
      "event": "User preference recorded",
      "description": "User prefers dark mode and compact layout",
      "score": 0.92,
      "timestamp": "2026-03-28T10:00:00Z",
      "importance": 7,
      "tags": ["preference"]
    }
  ],
  "total": 1,
  "query": "What does the user prefer?"
}
```

## Add Memory

Submit conversation messages to extract and store memories. The system identifies key information and creates structured memories. Async processing is supported for non-blocking calls.

```text
POST /api/plugin/v1/add/message
```

### Request Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `conversation_id` | string | Yes | - | Unique conversation identifier used to group related messages. |
| `messages` | array | Yes | - | Message objects with `role` (`user` or `assistant`) and `content` string. |
| `user_id` | string | No | - | User identifier for memory isolation. |
| `tags` | string[] | No | `["openclaw"]` | Custom tags for categorization and filtering. |
| `source` | string | No | `"openclaw"` | Source identifier. The plugin does not send this field; the server defaults to `openclaw`. |
| `agent_id` | string | No | `null` | Optional agent identifier for multi-agent scenarios. |
| `app_id` | string | No | `null` | Optional application identifier. The plugin does not send this field. |
| `async_mode` | boolean | No | `true` | Process in the background if true, or wait for completion if false. |

### cURL Example

```bash
curl -X POST https://plugin.human-like.me/api/plugin/v1/add/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "conversation_id": "conv_001",
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "I prefer dark mode for all interfaces"},
      {"role": "assistant", "content": "Got it, I will remember your dark mode preference!"}
    ],
    "tags": ["preference"],
    "async_mode": true
  }'
```

### Python Example

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://plugin.human-like.me"

response = requests.post(
    f"{BASE_URL}/api/plugin/v1/add/message",
    headers={
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "conversation_id": "conv_001",
        "user_id": "user_001",
        "messages": [
            {"role": "user", "content": "I prefer dark mode for all interfaces"},
            {"role": "assistant", "content": "Got it, I will remember your dark mode preference!"},
        ],
        "tags": ["preference"],
        "async_mode": True,
    },
)

data = response.json()
if data["success"]:
    print(f"Stored {data['memories_count']} memories")
    for mem in data["memories"]:
        print(f"  - {mem['description']}")
else:
    print(f"Error: {data.get('error')}")
```

### Response Example

```json
{
  "success": true,
  "message": "Memories processed successfully",
  "memories_count": 1,
  "memories": [
    {
      "id": "mem_xyz789",
      "conversation_id": "conv_001",
      "event": "User preference update",
      "description": "User prefers dark mode for all interfaces",
      "timestamp": "2026-03-28T10:30:00Z",
      "importance": 6,
      "tags": ["preference"]
    }
  ]
}
```

## Quick Start

1. Create an API key in the Dashboard under `API Keys`.
2. Copy a cURL or Python example above and replace `YOUR_API_KEY` with your real key.
3. Call Search Memory before generating AI responses to inject relevant context.
4. Call Add Memory after conversations to persist important information.