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

# Consolidate Memories

> POST /v1/memories/consolidate — Auto-merge similar memories to reduce redundancy.

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

**Price:** \$0.01 USDC

Consolidate automatically finds and merges semantically similar memories. It uses vector similarity to identify clusters of redundant memories and merges them via rule-based or LLM-powered strategies.

## Request Body

All fields are optional. The API auto-discovers similar memory pairs.

<ParamField body="min_similarity" type="number">
  Minimum cosine similarity threshold for clustering (0.5–1.0). Default: `0.85`. Higher = stricter matching.
</ParamField>

<ParamField body="mode" type="string">
  Merge strategy:

  * `rule` (default): Keep highest-importance memory, merge tags, soft-delete rest. Creates `supersedes` relationships.
  * `llm`: Synthesize a new memory from the cluster via LLM. Creates `derived_from` relationships.
</ParamField>

<ParamField body="namespace" type="string">
  Only consolidate memories in this namespace.
</ParamField>

<ParamField body="dry_run" type="boolean">
  If `true`, return clusters that would be merged without actually merging. Default: `false`.
</ParamField>

## Response (200 OK)

<ResponseField name="clusters_found" type="number">
  Number of similar memory clusters found.
</ResponseField>

<ResponseField name="memories_merged" type="number">
  Number of memories that were soft-deleted (merged into others).
</ResponseField>

<ResponseField name="memories_created" type="number">
  Number of new synthesized memories (LLM mode only).
</ResponseField>

<ResponseField name="clusters" type="array">
  Details of each cluster.

  <Expandable title="Cluster fields">
    <ResponseField name="clusters[].memory_ids" type="string[]">
      IDs of memories in this cluster.
    </ResponseField>

    <ResponseField name="clusters[].similarity" type="number">
      Average pairwise similarity within the cluster.
    </ResponseField>

    <ResponseField name="clusters[].merged_into" type="string">
      ID of the surviving/synthesized memory (absent in dry\_run).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.memoclaw.com/v1/memories/consolidate \
    -H "Content-Type: application/json" \
    -d '{
      "min_similarity": 0.85,
      "mode": "rule",
      "dry_run": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.memoclaw.com/v1/memories/consolidate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      min_similarity: 0.85,
      mode: "rule",
      dry_run: true,
    }),
  });

  const data = await response.json();
  ```

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

  client = MemoClaw()
  result = client.consolidate(min_similarity=0.85, mode="rule", dry_run=True)
  ```
</CodeGroup>

```json Response theme={null}
{
  "clusters_found": 2,
  "memories_merged": 3,
  "memories_created": 0,
  "clusters": [
    {
      "memory_ids": ["uuid-1", "uuid-2"],
      "similarity": 0.92,
      "merged_into": "uuid-1"
    },
    {
      "memory_ids": ["uuid-3", "uuid-4", "uuid-5"],
      "similarity": 0.87,
      "merged_into": "uuid-3"
    }
  ]
}
```

<Note>
  In `rule` mode, the highest-importance memory survives and inherits tags from all merged memories. In `llm` mode, a new memory is synthesized that combines all unique information from the cluster.
</Note>