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

# Consolidate

> Run the memory lifecycle pipeline — decay, prune, and compress memories to keep your knowledge graph sharp.

<Note>**Cost:** 3 operations per call</Note>

## `POST /brain/consolidate`

Runs the full memory lifecycle pipeline for your account:

1. **Temporal decay** — applies the Ebbinghaus forgetting curve to all relationship confidences. Memories that haven't been accessed recently lose confidence exponentially.
2. **Pruning** — removes relationships whose confidence has fallen below the survival threshold (`PRUNE_THRESHOLD`, default `0.05`). Orphaned nodes are also cleaned up.
3. **Cluster compression** (requires OpenAI) — identifies densely connected entity clusters and uses an LLM to compress related facts into higher-level abstractions.

<Tip>
  Consolidation runs automatically every hour in the background. Call this endpoint manually only when you want to force an immediate cleanup — for example, after a large batch ingestion.
</Tip>

***

## Request body

```json theme={null}
{
  "persona": "shared",
  "force": false
}
```

| Field     | Type     | Required | Default | Description                                   |
| --------- | -------- | -------- | ------- | --------------------------------------------- |
| `persona` | `string` |          | `null`  | Restrict consolidation to a specific persona. |
| `force`   | `bool`   |          | `false` | Force consolidation even if it ran recently.  |

***

## Response

```json theme={null}
{
  "memories_reinforced": 0,
  "memories_decayed": 142,
  "memories_pruned": 17,
  "memories_compressed": 43,
  "abstractions_created": 8,
  "latency_ms": 3241.0
}
```

| Field                  | Type    | Description                                                            |
| ---------------------- | ------- | ---------------------------------------------------------------------- |
| `memories_decayed`     | `int`   | Relationships whose confidence was reduced by the forgetting curve.    |
| `memories_pruned`      | `int`   | Relationships and episodic chunks deleted for falling below threshold. |
| `memories_compressed`  | `int`   | Individual facts merged into cluster abstractions.                     |
| `abstractions_created` | `int`   | New higher-level summary nodes created in the knowledge graph.         |
| `latency_ms`           | `float` | Total time in milliseconds.                                            |

***

## Code examples

<CodeGroup>
  ```python Python SDK theme={null}
  from atlas_mem import AtlasMem

  brain = AtlasMem(api_key="atlas_...", base_url="https://api.bsyncs.com", user_id="user-123")

  # Standard consolidation
  result = brain.consolidate()
  print(f"Pruned {result['memories_pruned']} stale memories")
  print(f"Created {result['abstractions_created']} abstractions")

  # Force immediate consolidation
  result = brain.consolidate(force=True)
  ```

  ```python Python (requests) theme={null}
  import requests

  response = requests.post(
      "https://api.bsyncs.com/brain/consolidate",
      headers={
          "x-api-key": "atlas_your_key_here",
          "Content-Type": "application/json",
      },
      json={
          "persona": "shared",
          "force": True,
      }
  )
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.bsyncs.com/brain/consolidate \
    -H "x-api-key: atlas_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"force": true}'
  ```
</CodeGroup>

***

## Prune only — `POST /brain/prune`

If you only want to remove low-confidence memories without running decay or compression:

<Note>**Cost:** 1 operation per call</Note>

```json theme={null}
{
  "threshold": 0.05,
  "dry_run": true,
  "persona": "shared"
}
```

| Field       | Type     | Required | Default | Description                                             |
| ----------- | -------- | -------- | ------- | ------------------------------------------------------- |
| `threshold` | `float`  |          | `0.05`  | Confidence below which memories are pruned.             |
| `dry_run`   | `bool`   |          | `true`  | If `true`, returns the count without deleting anything. |
| `persona`   | `string` |          | `null`  | Restrict pruning to a persona.                          |

**Always run `dry_run: true` first:**

```python theme={null}
# Preview — how many memories are below threshold?
preview = brain.prune(threshold=0.1, dry_run=True)
print(f"{preview['candidates']} memories eligible for pruning")

# Execute if satisfied
result = brain.prune(threshold=0.1, dry_run=False)
print(f"{result['pruned']} memories deleted")
```

***

## Memory decay explained

Atlas uses the **Ebbinghaus forgetting curve**: `R = e^(-t/S)`, where:

* `R` = retention (applied to relationship confidence)
* `t` = time since last access (days)
* `S` = memory stability = `DECAY_HALF_LIFE_DAYS / ln(2)`

With the default `DECAY_HALF_LIFE_DAYS=7`, a memory not accessed for:

| Days elapsed | Confidence multiplier |
| ------------ | --------------------- |
| 1 day        | \~0.91×               |
| 7 days       | \~0.50×               |
| 14 days      | \~0.25×               |
| 30 days      | \~0.05× (prunable)    |

Memories that are frequently retrieved resist decay — each access resets the clock and reinforces the `access_count` frequency score.

***

## When to consolidate

<AccordionGroup>
  <Accordion title="After large batch ingestion">
    After loading a large document set, run consolidation to let the LLM compress related clusters into cleaner, higher-level abstractions before your agents start querying.
  </Accordion>

  <Accordion title="Weekly maintenance">
    Run a weekly `force: true` consolidation to prune knowledge that hasn't been accessed and keep your Qdrant and Neo4j stores lean.
  </Accordion>

  <Accordion title="Before a new project phase">
    When a project moves to a new phase and old facts are no longer relevant, lower `PRUNE_THRESHOLD` temporarily and run a forced consolidation to clean out stale context.
  </Accordion>
</AccordionGroup>