# Getting Started

<!-- Canonical: https://www.atlaso.ai/docs/quickstart -->

## Install

```bash
pip install atlaso
```

Tested on CPython 3.10, 3.11, 3.12, 3.13. The only runtime dependency is `httpx>=0.27,<0.29`. Atlaso never imports an LLM client.

### Optional extras

```bash
# MCP server (fastmcp) — real
pip install "atlaso[mcp]"

# Reserved namespaces — no code, just the name (warning on Memory() construction)
pip install "atlaso[langchain]"
pip install "atlaso[llamaindex]"
pip install "atlaso[dspy]"
pip install "atlaso[openai-agents]"
pip install "atlaso[crewai]"
```

### Verify

```bash
atlaso doctor
```

The doctor runs an end-to-end sanity check: imports, vendored engine, resolved storage path with source, and an `add` → `recall` → `retract` round-trip in a tempdir. Returns `0` on a healthy install.

---

## Quickstart

Five minutes from `pip install` to a working conflict-flagging loop.

### 1. Bind to a user

```python
from atlaso import Memory

m = Memory()                    # resolves <project-root>/.atlaso/ on first call
user = m.for_user("alice")      # frozen handle bound to alice
```

Always pass an authenticated identity to `for_user(...)` — never a value from a request body. The handle pre-fills `user_id` on every call.

### 2. Write a deposit

```python
result = user.add("Alice prefers oat milk in lattes")
print(result.id)
print(result.deposit.polarity, result.deposit.evidence_grade)
# open anecdotal
```

Defaults: `polarity="open"`, `evidence_grade="anecdotal"`, `scope=None`. No Field 3.0 ceremony required for casual notes.

### 3. Recall

```python
results = user.recall("milk", limit=5)
print(results.explain())                  # bag-level verdict
for r in results:
    print(r.is_confident, r.content)
```

### 4. Plant a conflict, watch the bag light up

```python
from atlaso import Scope

# env= satisfies the gate's provenance rule for narrow-negative
scope = Scope(model="gpt-5", dataset="prod-2026", env="prod")

user.add("threshold 0.7 is optimal",
         polarity="positive", evidence_grade="observed", scope=scope)
user.add("threshold 0.7 over-flags",
         polarity="negative", evidence_grade="observed", scope=scope)

hits = user.recall("threshold", scope=scope)
print(hits.has_disagreement)                 # True
for h in hits:
    print(h.has_disagreement, h.content, "peers:", h.conflict_peers)
```

### 5. Supersede instead of update

Deposits are immutable. `m.update(...)` raises `AttributeError` pointing at `contradict()`.

```python
old = user.add("Alice prefers oat milk")
new = user.contradict(
    "Alice now prefers soy milk",
    contradicts=[old.id],
    reason="Apr-23 conversation update",
)
print(new.deposit.id, "supersedes", old.id)
```

### 6. Retract (soft by default, hard for GDPR)

```python
user.retract(new.deposit.id, reason="customer request")              # soft tombstone
user.retract(new.deposit.id, reason="GDPR erasure", hard_delete=True)  # irreversible
```

### 7. Health check

```python
diag = user.health(window_days=30)
print(diag.fmi, diag.coverage, diag.precision, diag.resolution, diag.density)
print(diag.explain())
# "Memory is healthy (FMI 72/100). Searches are returning confident answers."
```

---

## What's next

- [Concepts](./concepts.md) — Field 3.0 mental model in detail.
- [API Reference](./api-reference.md) — every method, every kwarg.
- [CLI](./cli.md) — `atlaso add`, `atlaso recall`, …
- [MCP & Hooks](./mcp-and-hooks.md) — run as an MCP server for Claude Code / Cursor / Codex.

---

<!-- atlaso:doc-trailer -->
**Source:** <https://www.atlaso.ai/docs/quickstart>  
**Edit on GitHub:** <https://github.com/imashishkh21/atlaso/tree/main/docs/getting-started.md>  
**Updated:** 2026-05-12