> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sinas.co/llms.txt
> Use this file to discover all available pages before exploring further.

# States

> Key-value stores with encryption and visibility

States are a persistent key-value store organized by namespace. Agents use states to maintain memory and context across conversations.

**Key properties:**

| Property          | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `namespace`       | Organizational grouping (e.g., `preferences`, `memory`, `api_keys`)         |
| `key`             | Unique key within user + namespace                                          |
| `value`           | Any JSON data                                                               |
| `visibility`      | `private` (owner only) or `shared` (users with namespace `:all` permission) |
| `description`     | Optional description                                                        |
| `tags`            | Tags for filtering and search                                               |
| `relevance_score` | Priority for context retrieval (0.0–1.0, default: 1.0)                      |
| `encrypted`       | If `true`, value is encrypted at rest with Fernet and decrypted on read     |
| `expires_at`      | Optional 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`:

```yaml theme={null}
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
```

***