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