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

# Persistent Storage

> Learn how to implement persistent storage in your Dify plugins using the built-in key-value database to maintain state across interactions.

## Overview

Most plugin tools and endpoints operate in a stateless, single-round interaction model:

1. Receive a request
2. Process data
3. Return a response
4. End the interaction

However, many real-world applications require maintaining state across multiple interactions. This is where **persistent storage** becomes essential.

<Info>
  The persistent storage mechanism allows plugins to store data persistently within the same workspace, enabling stateful applications and memory features.
</Info>

Dify currently provides a key-value (KV) storage system for plugins, with plans to introduce more flexible and powerful storage interfaces in the future based on developer needs.

## Access Storage

All storage operations are performed through the `storage` object available in your plugin's session:

```python theme={null}
# Access the storage interface
storage = self.session.storage
```

## Storage Operations

### Store Data

Store data with the `set` method:

```python theme={null}
def set(self, key: str, val: bytes) -> None:
    """
    Store data in persistent storage
    
    Parameters:
        key: Unique identifier for your data
        val: Binary data to store (bytes)
    """
    pass
```

<Warning>
  The value must be in `bytes` format. This provides flexibility to store various types of data, including files.
</Warning>

#### Example: Storing Different Data Types

```python theme={null}
# String data (must convert to bytes)
storage.set("user_name", "John Doe".encode('utf-8'))

# JSON data
import json
user_data = {"name": "John", "age": 30, "preferences": ["AI", "NLP"]}
storage.set("user_data", json.dumps(user_data).encode('utf-8'))

# File data
with open("image.jpg", "rb") as f:
    image_data = f.read()
    storage.set("profile_image", image_data)
```

### Retrieve Data

Retrieve stored data with the `get` method:

```python theme={null}
def get(self, key: str) -> bytes:
    """
    Retrieve data from persistent storage
    
    Parameters:
        key: Unique identifier for your data
        
    Returns:
        The stored data as bytes, or None if key doesn't exist
    """
    pass
```

#### Example: Retrieving and Converting Data

```python theme={null}
# Retrieving string data
name_bytes = storage.get("user_name")
if name_bytes:
    name = name_bytes.decode('utf-8')
    print(f"Retrieved name: {name}")

# Retrieving JSON data
import json
user_data_bytes = storage.get("user_data")
if user_data_bytes:
    user_data = json.loads(user_data_bytes.decode('utf-8'))
    print(f"User preferences: {user_data['preferences']}")
```

### Delete Data

Delete stored data with the `delete` method:

```python theme={null}
def delete(self, key: str) -> None:
    """
    Delete data from persistent storage
    
    Parameters:
        key: Unique identifier for the data to delete
    """
    pass
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Descriptive Keys" icon="key">
    Create a consistent naming scheme for your keys to avoid conflicts and make your code more maintainable.
  </Card>

  <Card title="Handle Missing Keys" icon="triangle-exclamation">
    Always check if data exists before processing it, as the key might not be found.
  </Card>

  <Card title="Serialize Complex Data" icon="code">
    Convert complex objects to JSON or other serialized formats before storing.
  </Card>

  <Card title="Implement Error Handling" icon="shield">
    Wrap storage operations in try/except blocks to handle potential errors gracefully.
  </Card>
</CardGroup>

## Common Use Cases

* **User Preferences**: Store user settings and preferences between sessions
* **Conversation History**: Maintain context from previous conversations
* **API Tokens**: Store authentication tokens securely
* **Cached Data**: Store frequently accessed data to reduce API calls
* **File Storage**: Store user-uploaded files or generated content

***

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/features-and-specs/plugin-types/persistent-storage-kv.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)