Skip to main content

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.

Cost: 3 operations per call

​
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.
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
}
FieldTypeRequiredDefaultDescription
personastringnullRestrict consolidation to a specific persona.
forceboolfalseForce 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
}
FieldTypeDescription
memories_decayedintRelationships whose confidence was reduced by the forgetting curve.
memories_prunedintRelationships and episodic chunks deleted for falling below threshold.
memories_compressedintIndividual facts merged into cluster abstractions.
abstractions_createdintNew higher-level summary nodes created in the knowledge graph.
latency_msfloatTotal 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)

​
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"
}
FieldTypeRequiredDefaultDescription
thresholdfloat0.05Confidence below which memories are pruned.
dry_runbooltrueIf true, returns the count without deleting anything.
personastringnullRestrict 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 elapsedConfidence 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 loading a large document set, run consolidation to let the LLM compress related clusters into cleaner, higher-level abstractions before your agents start querying.
Run a weekly force: true consolidation to prune knowledge that hasn’t been accessed and keep your Qdrant and Neo4j stores lean.
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.