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

# Custom tracker store

> Write a tracker store that saves conversation history in your own database, or change the built-in tracker stores (SQL, Redis, MongoDB, DynamoDB).

A tracker store saves and loads the history of each conversation. The history is
the tracker: every event the conversation produced, such as user messages, agent
replies, and memory changes. Mantle ships `in_memory`, `redis`, `mongod`, `sql`, and
`dynamo` stores. Write your own when your database is none of those, or subclass
a built-in to change how it behaves.

## Before you start

Put your code in a package next to `agent.yml`: a folder named `addons/` with an
empty `__init__.py` file. Start `rasa` from the project root so the package can
be imported.

## Subclass `BaseTrackerStore`

Import `BaseTrackerStore` and `DialogueStateTracker` from `rasa.api.tracker.v1`.
Implement the four methods in the table below. `BaseTrackerStore` provides the
rest, including creating the tracker for a new conversation and the session
handling around each save.

```python addons/custom_tracker_store.py theme={null}
import json
from typing import Iterable, Optional

from rasa.api.tracker.v1 import (
    BaseTrackerStore,
    DialogueStateTracker,
    TrackerStoreSettings,
)


class MyTrackerStore(BaseTrackerStore):
    def __init__(self) -> None:
        super().__init__()
        self.trackers: dict[str, str] = {}

    def connect(self, settings: TrackerStoreSettings) -> None:
        """Read settings from integrations.yml. Mantle calls this once at startup."""
        self.endpoint = settings.params["endpoint"]

    async def save_tracker(self, tracker: DialogueStateTracker) -> None:
        """Store the tracker's events for its sender. Mantle calls this after each turn."""
        dialogue = tracker.as_dialogue().as_dict()
        dialogue["events"] = [event.as_dict() for event in tracker.events]
        self.trackers[tracker.sender_id] = json.dumps(dialogue)

    async def retrieve_tracker(
        self, conversation_id: str
    ) -> Optional[DialogueStateTracker]:
        """Return the stored tracker for a conversation, or None if it has none."""
        serialised = self.trackers.get(conversation_id)
        if serialised is None:
            return None
        return self.deserialise_tracker(conversation_id, serialised)

    async def tracker_keys(self) -> Iterable[str]:
        """Return the IDs of all stored conversations."""
        return list(self.trackers.keys())
```

This example keeps trackers in a dictionary so you can run it as written.
Replace the dictionary calls with your database calls. Keep the serialization
as JSON: `deserialise_tracker` reads JSON only.

The conversation id is the same value in both methods. The tracker stores it as
`sender_id`. `retrieve_tracker` names that argument `conversation_id`.

| Method | Required | Purpose |
| - | - | - |
| `connect(settings)` | yes | Open your connection, using `settings.params` |
| `save_tracker(tracker)` | yes | Store the tracker's events for `tracker.sender_id` |
| `retrieve_tracker(conversation_id)` | yes | Return the stored tracker, or `None` if the conversation has none |
| `tracker_keys()` | yes | Return the conversation IDs the store holds |
| `delete(conversation_id)` | no | Remove a conversation. Raises `NotImplementedError` until you override it |
| `update(tracker)` | no | Replace a stored tracker. Raises `NotImplementedError` until you override it |

`BaseTrackerStore` builds `retrieve_full_tracker`, `keys`, and `exists` on top of
the four required methods, so you do not implement them.

Register the class under `tracker_store`:

```yaml integrations.yml theme={null}
tracker_store:
  type: addons.custom_tracker_store.MyTrackerStore
  endpoint: ${TRACKER_STORE_ENDPOINT}
```

## Subclass the built-in Redis store

To change one behavior of the `redis` store and keep the rest, subclass
`RedisTrackerStore`. This example skips saving conversations from a test harness,
so they do not fill the database. The sender IDs of those conversations start
with `test-`.

```python addons/custom_redis_tracker_store.py theme={null}
from rasa.api.tracker.v1 import DialogueStateTracker, RedisTrackerStore


class MyRedisTrackerStore(RedisTrackerStore):
    async def save_tracker(self, tracker: DialogueStateTracker) -> None:
        """Skip test conversations, and save the rest with the built-in Redis store."""
        if tracker.sender_id.startswith("test-"):
            return
        await super().save_tracker(tracker)
```

```yaml integrations.yml theme={null}
tracker_store:
  type: addons.custom_redis_tracker_store.MyRedisTrackerStore
  host: ${REDIS_HOST}
  port: 6379
  password: ${REDIS_PASSWORD}
```

The keys in [`tracker_store`](https://rasa.com/docs/mantle/reference/integrations-yml#tracker_store) apply to
your subclass. Keep `type` set to the class path, because the built-in name
`redis` selects the built-in class.

## Versioning

The import `rasa.api.tracker.v1` is the version. YAML names only the class. See
[Custom integrations: Versioning](https://rasa.com/docs/mantle/reference/custom-integrations.md#versioning).


## Related topics

- [Tracker Stores](https://rasa.com/docs/reference/integrations/tracker-stores.md)
- [Custom integrations](https://rasa.com/docs/mantle/reference/custom-integrations.md)
- [Rasa Pro Version Migration Guide](https://rasa.com/docs/reference/changelogs/rasa-pro-migration-guide.md)
- [integrations.yml](https://rasa.com/docs/mantle/reference/integrations-yml.md)
- [User-Scoped Conversations](https://rasa.com/docs/reference/config/session-management/user-scoped-conversations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.