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

# Persistent Storage

> Configure persistence for AI conversations with OpenResponses

# Persistent Storage

OpenResponses provides configurable storage mechanisms for AI responses and their associated input items. This enables you to maintain conversation history and reference previous interactions in subsequent requests.

## Key Benefits

Unlike OpenAI's managed service, our Response Store implementation offers:

1. **Complete Data Control**: Store all your conversation data on your own infrastructure, ensuring data sovereignty and compliance with your organization's data policies.
2. **Flexible Storage Options**: Choose between in-memory storage for development or MongoDB for persistent storage in production environments.
3. **Customizable Retention**: Define your own data retention policies without being constrained by OpenAI's limits.
4. **Integration Flexibility**: Easily integrate with your existing systems and data pipelines for analytics, auditing, or other business processes.
5. **Cost Management**: Potentially reduce costs by optimizing storage and retrieval according to your specific usage patterns.

## Storage Options

OpenResponses supports two storage implementations:

<CardGroup cols={2}>
  <Card title="In-Memory Storage" icon="memory">
    Default option for development and testing. Fast but non-persistent.
  </Card>

  <Card title="MongoDB Storage" icon="database">
    Production-ready solution for persistent storage of conversations.
  </Card>
</CardGroup>

## Controlling Storage

Use the `store` parameter in your API requests to control whether responses are stored:

```json theme={null}
{
  "model": "openai@gpt-4o",
  "input": "Tell me a bedtime story about a unicorn.",
  "store": true  // Set to true to store the conversation
}
```

* When `store=true`, the response and its inputs are saved in the configured store.
* When `store=false` or omitted, no data is stored regardless of configuration.

## Configuration

### In-Memory Store (Default)

The in-memory store is enabled by default and requires no additional configuration. It's suitable for development and testing environments, but data will be lost when the application restarts.

To explicitly configure the in-memory store:

```properties theme={null}
open-responses.store.type=in-memory
```

### MongoDB Store

For production environments where persistence is required, the MongoDB store provides durable storage of response data.

To enable the MongoDB store:

1. Add the following properties to your configuration:

```properties theme={null}
open-responses.store.type=mongodb
open-responses.mongodb.uri=mongodb://localhost:27017
open-responses.mongodb.database=openresponses
```

2. Ensure you have MongoDB installed and running, or provide the connection string to your MongoDB instance.

You can also configure the response store using environment variables:

```bash theme={null}
# Set the response store type
export OPEN_RESPONSES_STORE_TYPE=mongodb

# Configure MongoDB (when using mongodb store type)
export OPEN_RESPONSES_MONGODB_URI=mongodb://localhost:27017
export OPEN_RESPONSES_MONGODB_DATABASE=openresponses
```

## Using with Docker Compose

To run OpenResponses with MongoDB for persistent storage:

```bash theme={null}
# Start MongoDB and OpenResponses
docker-compose --profile mongodb up -d
```

## API Usage Examples

### Storing a New Conversation

```bash theme={null}
curl http://localhost:6644/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "openai@gpt-4o",
    "input": [
      {"role": "user", "content": "Tell me a three sentence bedtime story about a unicorn."}
    ],
    "store": true
  }'
```

### Sample Response

When you make a request to store a conversation, you'll receive a response that includes a unique ID for that response. This ID can be used to continue the conversation later:

```json theme={null}
{
    "id": "chatcmpl-BLB88IDIyyHjupNiAqOZQvAfT2T3K",
    "created_at": 1744387372,
    "error": null,
    "incomplete_details": null,
    "instructions": null,
    "metadata": null,
    "model": "openai@gpt-4o-2024-08-06",
    "object": "response",
    "output": [
        {
            "id": "589f0a06-ad6e-4a65-ae9f-1d2189c07813",
            "content": [
                {
                    "annotations": [],
                    "text": "In the tranquil heart of an ancient forest...",
                    "type": "output_text"
                }
            ],
            "role": "assistant",
            "status": "completed",
            "type": "message"
        }
    ],
    "parallel_tool_calls": null,
    "temperature": 1.0,
    "tool_choice": "none",
    "top_p": null,
    "max_output_tokens": null,
    "previous_response_id": null,
    "reasoning": null,
    "status": "completed",
    "usage": {
        "input_tokens": 18,
        "output_tokens": 84,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 102
    }
}
```

### Continuing a Stored Conversation

To reference a previously stored conversation, use the response ID:

```bash theme={null}
curl http://localhost:6644/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "openai@gpt-4o",
    "previous_response_id": "chatcmpl-BLB88IDIyyHjupNiAqOZQvAfT2T3K",
    "input": [
      {"role": "user", "content": "Make the story longer."}
    ],
    "store": true
  }'
```

## Python SDK Example

* Usage Example Python OpenAI SDK example can be found here [example](https://github.com/masaic-ai-platform/openai-agents-python/blob/main/examples/open_responses/conversation_state.py)

## Best Practices

1. Only enable storage (`store=true`) for conversations that need persistence.
2. For ephemeral interactions, omit the `store` parameter or set it to `false`.
3. Use MongoDB storage in production for data durability.
4. Implement appropriate backup strategies for your MongoDB database.
5. Consider GDPR and other data protection regulations when storing conversation data.