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

# Global Settings

> Configure the AtlasMem client — scoring weights, memory parameters, personas, and session behaviour.

## SDK constructor options

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

```python theme={null}
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`:

```bash theme={null}
# 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
```

<Tip>
  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`.
</Tip>

***

## Memory lifecycle settings (self-hosted)

```bash theme={null}
# 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)

```bash theme={null}
# 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)

```bash theme={null}
# 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
```

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

***

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

```python theme={null}
# 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
```

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