UserHandle

Why a handle at all

Memory.add(...) requires user_idas a keyword argument on every call. That's correct but easy to fumble — a missed kwarg in one branch and you write to the wrong tenant. The handle solves it: bind once, call freely. The handle is also where a centralized validate_user_id callback fires, giving you a single audit point.

Bind once

from atlaso import Memory

m = Memory(validate_user_id=allowlist_check)

# In your request handler:
user = m.for_user(auth.user.id)   # validate_user_id runs once here
user.add("…")
hits = user.recall("…")

Methods

Every method matches its Memory counterpart minus the user_id= kwarg:

• user.add(text, *, polarity=..., evidence_grade=..., scope=..., tags=..., contradicts=..., author=None)
• user.recall(query, *, limit=10, scope=None)
• user.get(deposit_id)
• user.peek(*, limit=10)
• user.list_recent(*, limit=20, offset=0)
• user.contradict(new_text, contradicts, *, reason)
• user.retract(deposit_id, *, reason, hard_delete=False, force=False)
• user.health(*, window_days=30)
• user.add_many(items, *, on_gate_reject="skip")

user_id property

print(user.user_id)   # "alice"

Rebinding

The handle is frozen (slotted dataclass, no __setattr__). To rebind, call for_user(...) again on the underlying Memory instance. There is no handle.rebind() method by design.

Async handle

AsyncMemory.for_user(user_id) is also synchronous and returns an AsyncUserHandle with the same method names but every call awaitable.