Consolidate

Cost: 3 operations per call

`POST /brain/consolidate`

Runs the full memory lifecycle pipeline for your account:

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

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.

Request body

{
  "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

{
  "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

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)

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())

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}'

Prune only — `POST /brain/prune`

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

Cost: 1 operation per call

{
  "threshold": 0.05,
  "dry_run": true,
  "persona": "shared"
}

Field	Type	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:

# 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

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.

Weekly maintenance

Run a weekly force: true consolidation to prune knowledge that hasn’t been accessed and keep your Qdrant and Neo4j stores lean.

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.

API documentation

Endpoint examples

`POST /brain/consolidate`

Request body

Response

Code examples

Prune only — `POST /brain/prune`

Memory decay explained

When to consolidate

​POST /brain/consolidate

​Request body

​Response

​Code examples

​Prune only — POST /brain/prune

​Memory decay explained

​When to consolidate

`POST /brain/consolidate`

Request body

Response

Code examples

Prune only — `POST /brain/prune`

Memory decay explained

When to consolidate