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

# Memory Relations

> CRUD operations for memory relationships — link memories together.

<Snippet file="snippets/wallet-auth-callout.mdx" />

**Price:** FREE

Relations let you create explicit links between memories. Use them to build knowledge graphs, track contradictions, or group related facts.

## Relation Types

| Type           | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `related_to`   | General relationship between related memories                    |
| `derived_from` | Memory was derived/synthesized from another (e.g. consolidation) |
| `contradicts`  | Memories that conflict (useful for tracking corrections)         |
| `supersedes`   | New memory replaces old one                                      |
| `supports`     | Memory provides supporting evidence for another                  |

***

## POST /v1/memories/:id/relations

Create a relationship from one memory to another.

### Path Parameters

<ParamField path="id" type="string" required>
  Source memory UUID.
</ParamField>

### Request Body

<ParamField body="target_id" type="string" required>
  Target memory UUID to link to.
</ParamField>

<ParamField body="relation_type" type="string" required>
  One of: `related_to`, `derived_from`, `contradicts`, `supersedes`, `supports`.
</ParamField>

<ParamField body="metadata" type="object">
  Optional metadata for the relationship.
</ParamField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.memoclaw.com/v1/memories/550e8400-e29b-41d4-a716-446655440001/relations \
    -H "Content-Type: application/json" \
    -d '{
      "target_id": "550e8400-e29b-41d4-a716-446655440002",
      "relation_type": "supersedes",
      "metadata": {
        "reason": "User corrected their timezone preference"
      }
    }'
  ```

  ```python Python theme={null}
  from memoclaw import MemoClaw

  client = MemoClaw()
  relation = client.create_relation(
      "550e8400-e29b-41d4-a716-446655440001",
      target_id="550e8400-e29b-41d4-a716-446655440002",
      relation_type="supersedes",
      metadata={"reason": "User corrected their timezone preference"},
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "rel-123e4567-e89b-12d3-a456-426614174000",
  "source_id": "550e8400-e29b-41d4-a716-446655440001",
  "target_id": "550e8400-e29b-41d4-a716-446655440002",
  "relation_type": "supersedes",
  "metadata": {
    "reason": "User corrected their timezone preference"
  },
  "created_at": "2024-02-11T10:45:00Z"
}
```

***

## GET /v1/memories/:id/relations

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

### Path Parameters

<ParamField path="id" type="string" required>
  Memory UUID.
</ParamField>

### Example

```bash curl theme={null}
curl https://api.memoclaw.com/v1/memories/550e8400-e29b-41d4-a716-446655440001/relations
```

```json Response theme={null}
{
  "relations": [
    {
      "id": "rel-123e4567-e89b-12d3-a456-426614174000",
      "source_id": "550e8400-e29b-41d4-a716-446655440001",
      "target_id": "550e8400-e29b-41d4-a716-446655440002",
      "relation_type": "supersedes",
      "direction": "outgoing",
      "created_at": "2024-02-11T10:45:00Z"
    },
    {
      "id": "rel-223e4567-e89b-12d3-a456-426614174001",
      "source_id": "550e8400-e29b-41d4-a716-446655440005",
      "target_id": "550e8400-e29b-41d4-a716-446655440001",
      "relation_type": "supports",
      "direction": "incoming",
      "created_at": "2024-02-10T08:30:00Z"
    }
  ]
}
```

***

## DELETE /v1/memories/:id/relations/:relationId

Remove a relationship.

### Path Parameters

<ParamField path="id" type="string" required>
  Memory UUID.
</ParamField>

<ParamField path="relationId" type="string" required>
  Relation UUID to delete.
</ParamField>

### Example

```bash curl theme={null}
curl -X DELETE https://api.memoclaw.com/v1/memories/550e8400-e29b-41d4-a716-446655440001/relations/rel-123e4567-e89b-12d3-a456-426614174000
```

```json Response theme={null}
{
  "deleted": true
}
```