Skip to main content

Preferences

Agent Preferences: a per-agent key/value store for learned and explicit user preferences (timezone, tone, sign-off, etc.). Distinct from Memory: preferences are key-addressable and idempotent on key; memory is free-form and ranked by relevance.

Access it as client.preferences on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate)  # filters: search, category, preference_source, tags, include_superseded
for preference in client.preferences.list():
    print(preference.id)

# Create
created = client.preferences.create(
    key="...",
    value="...",
)
print(created.id)

# Read it back
fetched = client.preferences.retrieve(created.id)

# Delete (returns None; raises on failure)
client.preferences.delete(created.id)

Methods​

Core​

list​

list(*, search: Optional[str] = None, category: Optional[str] = None, preference_source: Optional[str] = None, tags: Optional[List[str]] = None, include_superseded: Optional[bool] = None, limit: Optional[int] = None) -> SyncPaginator[Preference]

List preferences with pagination and filters.

Args: search: Full-text search over key and value. category: Filter by category. preference_source: explicit | learned | inferred | imported | manual. tags: Filter by tags. include_superseded: Include archived (superseded) rows. limit: Maximum number of items to return (default: all matching items).

Returns: A paginator yielding Preference objects.

create​

create(*, key: str, value: Any, category: Optional[str] = None, preference_source: Optional[str] = None, confidence: Optional[float] = None, evidence: Optional[str] = None, tags: Optional[Sequence[str]] = None, scope: Optional[Mapping[str, Any]] = None) -> Preference

Create a preference (key and value required).

Upsert-by-key semantics: writing the same key+value twice is a no-op; a new value archives the old row in the supersedes chain. Alias of set.

set​

set(key: str, value: Any, *, category: Optional[str] = None, preference_source: Optional[str] = None, confidence: Optional[float] = None, evidence: Optional[str] = None, tags: Optional[Sequence[str]] = None, scope: Optional[Mapping[str, Any]] = None) -> Preference

Upsert a preference by key (idempotent on owner+scope+key).

Writing the same key+value twice is a no-op; writing a new value archives the old row in the supersedes chain. Convenience over create; both hit the same endpoint.

retrieve​

retrieve(preference_id: str) -> Preference

Retrieve a preference by id.

by_key​

by_key(key: str) -> Preference

Look up the current preference for a given key.

update​

update(preference_id: str, *, value: Any = None, category: Optional[str] = None, preference_source: Optional[str] = None, confidence: Optional[float] = None, evidence: Optional[str] = None, tags: Optional[Sequence[str]] = None) -> Preference

Update a preference and return the updated record.

delete​

delete(preference_id: str) -> None

Hard-delete a single preference by id. Raises on failure; returns nothing.

Sharing & scope​

share​

share(preference_id: str, user_id: str) -> Dict[str, Any]

Grant user_id access to this preference.

unshare​

unshare(preference_id: str, user_id: str) -> Dict[str, Any]

Revoke user_id's access to this preference.

toggle_public​

toggle_public(preference_id: str) -> Dict[str, Any]

Flip the public visibility flag on a preference.

update_scope​

update_scope(preference_id: str, *, scope: Optional[Dict[str, Any]] = None) -> Dict[str, Any]

Re-scope a preference (owner-only). An empty scope moves it to user-global.

Other​

forget​

forget(key: str, *, scope: Optional[Dict[str, Any]] = None) -> Dict[str, Any]

Forget a preference by key (chain-aware).

Removes the current row and breaks the supersedes chain. Pass an optional scope tuple {agentId?, appId?, workflowId?} to forget within a specific scope rather than the caller's default.