Skip to main content
persona.stores (sync) / await persona.stores (async) wraps /api/v1/developer/stores. Stores are named, scoped mount points you create and assign to Agents (Agent.storeMounts, settable via agents.update()), generalizing the fixed /memories/user///memories/agent/ mounts into arbitrarily-named ones. A Store is mounted at /stores/<name>/ in the Agent’s filesystem.
As of this release, the Python SDK doesn’t type storeMounts on its Agent/agents create/update inputs yet (the Node SDK does). At runtime the backend accepts it, but mypy/pyright won’t know about it — pass it as an extra dict key, or use the Node SDK for typed store mounting. See Compatibility — parity.

​
Ownership rules

  • Config CRUD (create/list/get/update/delete) works with a bare Project credential — a Store’s config isn’t per-founder. No external_user_id needed.
  • File CRUD is the same, except when the Store’s own scope is 'externalUser': only then does the client need to have been constructed with external_user_id set, or the call 400s with EXTERNAL_USER_REQUIRED. The check is server-side, per request after loading the store — a domain-scoped Store works from a bare credential, an externalUser-scoped Store doesn’t.

​
Methods

Async: identical methods with await.

​
create(input)

CreateStoreInput: name (required — lowercase letters, numbers, hyphens only), scope (required), plus optional description, accessMode (default 'readwrite'). scope cannot be changed after creation.
scope semantics: 'domain' — one shared namespace for the whole Project; 'externalUser' — one namespace per external user, resolved per Agent run. accessMode semantics: 'readonly' — Agents can read but never write via their own tool calls (content is populated only through this API); 'readwrite' — Agents can also write_file/edit_file into it. A 409 PersonaApiError is raised if a Store with this exact name already exists.

​
list(params=None) / get(store_id) / update(store_id, input) / delete(store_id)

list() takes DiscoverStoresParams (all optional): page (default 1), limit (default 20), search (free-text against name). Returns the standard PaginatedResult. update() accepts UpdateStoreInput: name?, description?, accessMode? — scope is deliberately not included (immutable after creation). Create a new Store if you need a different one. delete() removes the Store, also removes it from every Agent’s storeMounts, and purges all of its data — every founder’s partition, for an externalUser-scoped Store.

​
File CRUD

  • list_files() returns list[StoreFile] (the SDK unwraps the {files: [...]} envelope for you). For an externalUser-scoped Store it lists only this client’s asserted external user’s own partition — never another founder’s data, even to the same Project credential.
  • write_file() creates or overwrites — content replaces existing content entirely. Not gated by the Store’s accessMode: readonly only blocks an Agent’s own tool calls; this API is how a readonly Store’s content actually gets populated.
  • get_file()/delete_file() raise PersonaApiError (404) if the Store or file doesn’t exist.

​
Types

See Types — Store types for the full field reference: Store, StoreScope, StoreAccessMode, CreateStoreInput, UpdateStoreInput, DiscoverStoresParams, StoreFile, GetStoreFileParams, DeleteStoreFileParams, WriteStoreFileInput.