Configuration

Environment variables

ATLASO_PATH

Forces the base storage directory. Bypasses the project-marker walk. The path is expanded with ~ and resolved to absolute.

export ATLASO_PATH=/var/atlaso-data
python my_app.py

ATLASO_API_KEY

Reserved for the v0.2 remote backend. The MCP server warns to stderr if unset; the v0.1 local backend doesn't require it.

ATLASO_BASE_URL

Reserved for v0.2. Defaults to https://api.atlaso.dev.

ATLASO_ASYNC_WARNINGS

Set to 0 / false / no / off to suppress SyncInAsyncWarning process-wide. Unknown values default to ON (no silent disable on typo).

USER (read-only fallback for hooks)

The Claude Code hook scripts at ~/.atlaso/hooks/ resolve user_id from $ATLASO_USER with a fallback to the standard shell $USER. The SDK itself doesn't read these — they only affect hook behaviour.

ATLASO_TELEMETRY

Storage path resolution

With no path= and no ATLASO_PATH, atlaso walks from cwd outward:

1. Existing .atlaso/ in an ancestor wins.
2. Otherwise the nearest ancestor with pyproject.toml, package.json, .git, Cargo.toml, or go.mod wins; .atlaso/ is created there.
3. If none found, .atlaso/ is created in cwd.

Walk stops at $HOME or filesystem root, depth-capped at 64. There is no ~/.atlaso/ fallback.

atlaso doctor
# prints the resolved path + the source (constructor / env / walk)

Transport injection

For tests, inject an httpx.MockTransport instance. Atlaso refuses an httpx.Client here on purpose — the client holds Authorization headers, and sharing a client across tenants would leak them.

import httpx
from atlaso import Memory

def stub(request: httpx.Request) -> httpx.Response:
    return httpx.Response(200, json={"ok": True})

m = Memory(transport=httpx.MockTransport(stub))

Constructor knobs (recap)

Memory(
    api_key=None,             # v0.2 remote — env: ATLASO_API_KEY
    base_url=None,            # v0.2 remote — env: ATLASO_BASE_URL
    path=None,                # storage location — env: ATLASO_PATH
    validate_user_id=None,    # callable; raise to block
    timeout=10.0,
    max_retries=2,
    suppress_async_warning=None,   # env: ATLASO_ASYNC_WARNINGS
    transport=None,
)