> ## 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 knowledge store

> Write a knowledge store that searches documents in your own index, or change the built-in FAISS store, and register it under knowledge_stores.

A knowledge store is a searchable collection of documents. It takes a query and
returns the documents that match it. Mantle ships `faiss`, `qdrant`, and `milvus`
stores. Write your own when your search backend is none of those, or subclass a
built-in to change how it searches.

> [!NOTE]
>
> Mantle checks each `knowledge_stores:` entry when you run `rasa train`, but it
> does not query a knowledge store yet. The `search_knowledge` tool reads only the
> local index built from `references/`. See [What's next](https://rasa.com/docs/mantle/whats-next.md). You can
> write and register a knowledge store now so it is ready, but nothing calls its
> `search` method yet.

## 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 `KnowledgeStore`

Import `Document`, `KnowledgeStore`, `KnowledgeStoreSettings`, `SearchRequest`,
`SearchResult`, and `SearchResultList` from `rasa.api.knowledge.v1`. Implement
`connect` and `search`. The base class keeps the embeddings client in
`self.embeddings`, so you do not need to override `__init__`.

```python addons/custom_knowledge_store.py theme={null}
from rasa.api.knowledge.v1 import (
    Document,
    KnowledgeStore,
    KnowledgeStoreSettings,
    SearchRequest,
    SearchResult,
    SearchResultList,
)

FAQ_DOCUMENTS = [
    Document(text="Refunds take five business days to appear on your card."),
    Document(text="Shipping to Germany takes two business days."),
]


class MyKnowledgeStore(KnowledgeStore):
    def connect(self, settings: KnowledgeStoreSettings) -> None:
        """Load the documents when Mantle creates the store."""
        self.documents = FAQ_DOCUMENTS

    async def search(self, request: SearchRequest) -> SearchResultList:
        """Return the documents that match request.query. Mantle calls this when it queries the store."""
        words = request.query.lower().split()
        hits = [
            SearchResult.from_document(document)
            for document in self.documents
            if any(word in document.text.lower() for word in words)
        ]
        return SearchResultList(
            results=hits, metadata={"total_results": len(hits)}
        )
```

This example searches a list held in code, so it runs as written. Replace
`FAQ_DOCUMENTS` with a load from your index. The example matches words and ignores
`request.threshold`. A vector store would use the threshold to drop weak matches.

Add an embeddings model group in `integrations.yml` and name it in the entry. The
group must be a text embeddings model:

```yaml integrations.yml theme={null}
model_groups:
  - id: reference_embeddings
    models:
      - provider: openai
        model: text-embedding-3-large
        api_key: ${OPENAI_API_KEY}

knowledge_stores:
  - id: faq
    type: addons.custom_knowledge_store.MyKnowledgeStore
    embeddings: reference_embeddings
```

Each entry under `knowledge_stores:` accepts exactly three keys: `id`, `type`,
and `embeddings`. Any other key fails validation, so a store that needs its own
connection settings cannot take them yet. Store `id`s must be unique.

## Subclass the built-in FAISS store

To change how the `faiss` store returns results and keep the rest, subclass
`FAISSStore`. This example returns at most three hits:

```python addons/custom_faiss_store.py theme={null}
from rasa.api.knowledge.v1 import FAISSStore, SearchRequest, SearchResultList


class MyFAISSStore(FAISSStore):
    async def search(self, request: SearchRequest) -> SearchResultList:
        """Run the built-in search, then keep at most three hits."""
        result = await super().search(request)
        return SearchResultList(
            results=result.results[:3], metadata=result.metadata
        )
```

```yaml integrations.yml theme={null}
model_groups:
  - id: reference_embeddings
    models:
      - provider: openai
        model: text-embedding-3-large
        api_key: ${OPENAI_API_KEY}

knowledge_stores:
  - id: faq_faiss
    type: addons.custom_faiss_store.MyFAISSStore
    embeddings: reference_embeddings
```

Keep `type` set to the class path, because the built-in name `faiss` selects the
built-in class. Unlike other stages, `knowledge_stores` has no key for settings
such as an index path. A built-in FAISS store that needs an index path cannot be
configured from `integrations.yml` yet.

## Methods

| Method | Required | Purpose |
| - | - | - |
| `connect(settings)` | yes | Load or open your index. A `knowledge_stores` entry has no field for settings, so read configuration from code or from environment variables |
| `search(request)` | yes | Async. Return a `SearchResultList` for `request.query` |

## Versioning

The import `rasa.api.knowledge.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

- [Custom integrations](https://rasa.com/docs/mantle/reference/custom-integrations.md)
- [integrations.yml](https://rasa.com/docs/mantle/reference/integrations-yml.md)
- [Mantle Changelog](https://rasa.com/docs/mantle/changelog.md)
- [Custom lock store](https://rasa.com/docs/mantle/reference/custom-lock-store.md)
- [Custom timer store](https://rasa.com/docs/mantle/reference/custom-timer-store.md)


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