Frequently asked

No. The v0.1 local backend never makes an outbound request. The only network surface is the reserved v0.2 remote backend, which is off by default. ATLASO_TELEMETRYis a name-reserved no-op — set it truthy and you'll see a one-time UserWarning making the no-op explicit.

Lexical search is fast, deterministic, has no embedding service to host, and is verifiably reproducible across machines. The dispersion layer (the part of atlaso that flags conflicts) doesn't require semantic recall to work — it requires structured recall grouped by scope. v0.2 will add an optional embedding-backed path behind the same recall() signature.

Yes. Construct one Memory or AsyncMemory per process. On each request, call memory.for_user(authenticated_id) to get a UserHandle scoped to that user. The handle pre-fills the user_id on every method call, and per-user data lives at <base>/users/<sha256(user_id)[:16]>/field.db — one SQLite file per tenant, isolation enforced at the filesystem.

Because httpx.Client holds Authorization headers and sharing one across tenants risks silently leaking them. Atlaso accepts only httpx.BaseTransport (the connection layer, no headers). For tests, use httpx.MockTransport.

Storage resolves lazily on the first write, in this order: (1) the path= kwarg to Memory(), (2) the ATLASO_PATH env var, (3) the nearest ancestor that already contains a .atlaso/ directory, (4) the nearest ancestor with a project marker (pyproject.toml, package.json, .git, Cargo.toml, go.mod) — creates .atlaso/ there, (5) cwd as a last resort. The walk stops at $HOME or the filesystem root. There is no ~/.atlaso/ fallback for field data — a global home-dir store would silently merge memories across projects.

For a scope bag: bag_precision >= 0.99 AND not is_single_sample AND no has_conflict. All three must hold. A single observation is never confident regardless of evidence grade. Full derivation in Concepts · Confidence & conflict.

No — deposits are immutable on purpose. m.update(...) raises AttributeError with a pointer at contradict(). From a Memory instance, call m.contradict(new_text, contradicts=[old_id], reason=..., user_id=...); from a bound UserHandle, user.contradict(new_text, contradicts=[old_id], reason=...) (the handle pre-fills user_id). Atlaso writes the new deposit and records contradiction edges from old → new so the audit chain is preserved.

contradict() writes a new deposit and records a contradictsedge from the new one to each superseded id. Both deposits remain queryable for audit; the recall pipeline doesn't hard-filter contradicted targets but it surfaces the edge so your agent can branch on it. retract() removes a deposit from recall (soft tombstone by default; hard_delete=True is irreversible) without writing a replacement.

The gate refused the write. The exception's .gate_reason attribute tells you which rule fired and what to fix — usually you need a higher evidence grade, a narrower scope, or provenance (env / version / artifact_refs). See Architecture · The gate.

Yes, via MCP. Run pip install "atlaso[mcp]" then atlaso mcp. Add the server to your client's MCP config and you get the full nine-tool surface. Claude Code users also have an atlaso install-hooks command that wires automatic recall-on-prompt and deposit-on-stop hooks.

Use AsyncMemoryinside any async runtime (FastAPI, Starlette, asyncio loops). v0.1's async backend wraps the sync SQLite engine in asyncio.to_thread, so calls don't block the event loop. If you accidentally call synchronous Memory from an async handler, the SDK emits SyncInAsyncWarning once — silence with Memory(suppress_async_warning=True) or ATLASO_ASYNC_WARNINGS=0 if you have a deliberate reason. Note that for_user() stays sync on AsyncMemory; only the data methods are awaitable.

Pass an authenticated identity: whatever your auth middleware returned after verifying the user — a UUID, an email, a session-derived id. The shape constraint is ^[A-Za-z0-9_\-:.@]{1,128}$; spaces and slashes are rejected. Never pass a value from a request body — a client could pose as anyone. For a single audit point, pass validate_user_id= to the Memory() constructor: it runs inside every for_user(...) and every lower-level call. Raise from it to block.

Skip-and-report. Each AddItem requires an idempotency_key. Items that pass the gate land in result.committed; items where the key + identical content were seen in the last 24 hours land in result.duplicates (no second write); items the gate rejects land in result.failed as BulkReject(item, error, index) so you can retry the subset after fixing metadata. A same-key + different content collision raises IdempotencyKeyConflict with .existing_id.

Public API is design-locked for v0.1+. New methods may be added. Existing signatures, return types, and exception classes follow semver inside the alpha track — read the release notes before upgrading. Breaking changes are gated on a major version bump.