Global Settings

SDK constructor options

All configuration is passed to the AtlasMem (or AsyncAtlasMem) constructor. Every option has a sensible default.

from atlas_mem import AtlasMem

brain = AtlasMem(
    api_key="atlas_...",           # required
    base_url="https://api.bsyncs.com",  # required
    user_id="user-123",            # required — memory namespace
    session_id="session-abc",      # optional — enables working memory
    persona="shared",              # optional — sub-namespace within user
    timeout=300,                   # optional — HTTP timeout in seconds
    retries=3,                     # optional — retry attempts (sync only)
)

Parameter	Type	Default	Description
`api_key`	`str`	—	Your Atlas API key.
`base_url`	`str`	—	Base URL of your Atlas instance or `https://atlas.bsyncs.com`.
`user_id`	`str`	`"default"`	Tenant/user namespace — all memory reads and writes are scoped to this ID.
`session_id`	`str`	`None`	Session identifier for working memory. Enables rolling topic vectors and hot-fact caching.
`persona`	`str`	`"shared"`	Sub-namespace within a user. Useful for agent role separation (e.g. `"assistant"`, `"analyst"`).
`timeout`	`int`	`300`	HTTP request timeout in seconds. Increase for `graph_qa` on large graphs.
`retries`	`int`	`3`	Auto-retry count on 429 / 503 / 504 responses (sync client only).

Server-side scoring weights

Variable	Meaning	Default weight
V	Vector cosine similarity between query and fact	`α = 0.30`
R	Temporal recency — exponential decay since creation	`β = 0.35`
F	Access frequency — log-scaled hit count	`γ = 0.10`
A	Graph association strength — relation-query alignment	`δ = 0.25`

These are configured via environment variables on the server. If you are self-hosting, set them in your .env:

# Scoring weights (must sum to ~1.0)
SCORE_ALPHA=0.30    # vector similarity
SCORE_BETA=0.35     # recency
SCORE_GAMMA=0.10    # frequency
SCORE_DELTA=0.25    # graph association

# Minimum vector similarity to include a result (raise to filter noise)
SCORE_V_FLOOR=0.10

If your use case is knowledge-base QA (facts rarely change), increase SCORE_ALPHA and reduce SCORE_BETA. If it is a conversational agent (recency matters), keep the defaults or raise SCORE_BETA.

Memory lifecycle settings (self-hosted)

# Ebbinghaus half-life — how fast memories decay (days)
DECAY_HALF_LIFE_DAYS=7

# Confidence below which memories are eligible for pruning
PRUNE_THRESHOLD=0.05

# How often the background consolidation task runs (seconds)
CONSOLIDATION_INTERVAL_SECS=3600

# Working memory TTL — session data expires after this many seconds
WORKING_MEMORY_TTL_SECS=1800

# Max conversation turns stored per session
MAX_WORKING_MEMORY_ITEMS=50

Ingestion settings (self-hosted)

# SemanticChunker target chunk size (characters)
MAX_CHUNK_SIZE=512
CHUNK_OVERLAP=64

# Minimum text length to attempt extraction (shorter texts are skipped)
MIN_EXTRACTABLE_LENGTH=10

# Deduplication threshold — texts with cosine similarity above this are skipped
DEDUP_SIMILARITY_THRESHOLD=0.92

LLM & embedding models (self-hosted)

# OpenAI — powers LLMGraphTransformer and graph QA
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4.1
LLM_TEMPERATURE=0.05

# Embedding model (must match EMBEDDING_DIM)
EMBEDDING_MODEL=all-MiniLM-L6-v2
EMBEDDING_DIM=384

The embedding model is downloaded once and cached in the Docker image at build time. Changing EMBEDDING_MODEL requires rebuilding your base image.

Personas explained

Personas are sub-namespaces within a user. Use them when a single user ID needs to store memories across different agent roles without cross-contamination.

# Store memories as the "analyst" persona
analyst_brain = AtlasMem(
    api_key="atlas_...",
    user_id="user-123",
    persona="analyst",
)

# Store memories as the "assistant" persona
assistant_brain = AtlasMem(
    api_key="atlas_...",
    user_id="user-123",
    persona="assistant",
)

# Search is scoped to the persona
analyst_brain.search("quarterly revenue")    # only returns analyst memories
assistant_brain.search("quarterly revenue")  # only returns assistant memories

The "shared" persona is readable by all persona retrievals for the same user_id. Use it for global facts that should always be visible regardless of role.

Getting started

Customization

AI tools

SDK constructor options

Server-side scoring weights

Memory lifecycle settings (self-hosted)

Ingestion settings (self-hosted)

LLM & embedding models (self-hosted)

Personas explained

​SDK constructor options

​Server-side scoring weights

​Memory lifecycle settings (self-hosted)

​Ingestion settings (self-hosted)

​LLM & embedding models (self-hosted)

​Personas explained

SDK constructor options

Server-side scoring weights

Memory lifecycle settings (self-hosted)

Ingestion settings (self-hosted)

LLM & embedding models (self-hosted)

Personas explained