Skip to main content
States are a persistent key-value store organized by namespace. Agents use states to maintain memory and context across conversations. Key properties:
PropertyDescription
namespaceOrganizational grouping (e.g., preferences, memory, api_keys)
keyUnique key within user + namespace
valueAny JSON data
visibilityprivate (owner only) or shared (users with namespace :all permission)
descriptionOptional description
tagsTags for filtering and search
relevance_scorePriority for context retrieval (0.0–1.0, default: 1.0)
encryptedIf true, value is encrypted at rest with Fernet and decrypted on read
expires_atOptional expiration time
Encrypted states: Set encrypted: true when creating or updating a state to store the value encrypted. The plaintext value is stored in encrypted_value (Fernet-encrypted) while value is set to {}. On read, the value is transparently decrypted. This is useful for storing API keys, tokens, or other secrets. Agent state access is declared per agent via enabled_stores: 
enabledStores:
  - store: "shared_knowledge/main"
    access: readonly
  - store: "conversation_memory/main"
    access: readwrite
Read-only stores give the agent a retrieve_context tool. Read-write stores additionally provide save_context, update_context, and delete_context. Endpoints: 
POST   /states              # Create state entry
GET    /states              # List (supports namespace, visibility, tags, search filters)
GET    /states/{id}         # Get state
PUT    /states/{id}         # Update state
DELETE /states/{id}         # Delete state