Deposits

Anatomy

Every deposit carries:

• content — the plain-English claim.
• polarity — direction of the claim: positive / negative / cautionary / open.
• evidence_grade — how well-supported it is: anecdotal / observed / replicated / verified.
• scope — six facets pinning the claim to a context.
• tags, artifact_refs — free-form context.
• contradicts — directional supersession edges to earlier deposits.
• Provenance — author, author_role, task_id, created_at.

Immutability is a feature

Deposits cannot be edited in place. The SDK has no update() method — calling it raises AttributeError with a pointer at contradict(). Updating a fact creates a new deposit that supersedes the old one. The supersession edge is preserved in the contradictions table so the audit trail survives.

m.update("anything")
# AttributeError: deposits are immutable.
# Use m.contradict(new_text, contradicts=[old.id], reason="…") instead.

Writing one

from atlaso import Memory, Scope

m = Memory()
user = m.for_user("alice")

user.add(
    "Threshold of 0.7 over-flags in production",
    polarity="negative",
    evidence_grade="observed",
    scope=Scope(model="gpt-5", env="prod"),
    tags=["threshold", "fp-rate"],
)

Defaults: polarity="open", evidence_grade="anecdotal", scope=None. Most one-off facts can be written with no ceremony.

The gate may say no

Atlaso's gaterejects writes that don't carry the evidence their breadth requires. A broad positive ("X always works") needs replicated evidence; a narrow negative needs provenance (artifact_refs or a scoped env / version); cautionary claims need provenance.

from atlaso import DepositRejectedError

try:
    user.add(
        "Always use threshold 0.7",
        polarity="positive",
        evidence_grade="anecdotal",   # too weak for "always"
    )
except DepositRejectedError as e:
    print(e.gate_reason)
    # e.g. "positive/broad claim requires evidence_grade>=replicated"

Bulk imports

add_many() writes many deposits with per-item commit-and-report semantics — successful items land in result.committed, idempotent replays in result.duplicates, gate rejections in result.failed. Each item requires an idempotency_key so retries are safe — see Idempotency.

from atlaso import AddItem, idempotency_key

items = [
    AddItem(content=f"row {i}", idempotency_key=idempotency_key("alice", f"row {i}", "2026"))
    for i in range(100)
]
result = user.add_many(items)
print(result.total, result.committed, result.duplicates, result.failed)