Knowledge Banks

A Knowledge Bank is a vector store an agent retrieves from (RAG). You load documents into it, they are chunked and embedded, and at query time the agent pulls the most relevant chunks to ground its answer. A Knowledge Bank is org-scoped and reusable — several agents can retrieve from the same bank.

Adding documents

Two paths populate a Knowledge Bank:

• Direct upload — drop .md or text files into the bank from its page (POST /knowledge-bases/{kb_id}/docs). Each file is chunked and embedded on ingest.
• Embed recipe — the embed recipe on the Flow embeds a dataset's text column into a bank, so a governed table becomes retrievable.

Settings

Each bank has a settings editor:

Setting	What it controls
embedding_model	The model that turns text into vectors. Its output dimension must match the backing vector store.
chunk_size / chunk_overlap	How documents are split before embedding.
top_k	How many chunks a retrieval returns.
similarity_threshold	The minimum score a chunk must clear to be returned.

Vector-store backends

The embedding/vector-store wiring is registry-driven: the bank declares a backend and the platform resolves it, checking that the embedding dimension matches.

Backend	Notes
Built-in numpy store	The zero-dependency default. Ships in every install (compiled builds cannot load chromadb due to an ABI constraint, so the numpy store is the floor).
Chroma	Via the chroma connector.
FAISS	Via the faiss connector.
Pinecone	Managed store via the pinecone connector (mirrors the Chroma contract).

✦Honest degrade

If a bank's configured vector-store backend is unreachable, retrieval returns a 503 (VectorStoreUnavailable) rather than silently answering ungrounded. Fix the backend — the agent never fabricates around a missing store.

Retrieval & re-ranking

By default (HONEYFRAME_RAG_RERANK, on) retrieved chunks pass through a hybrid vector + lexical re-ranker (alpha=0.7) that reorders the top_k set for relevance. It only reorders — it never drops a chunk that cleared the similarity threshold.

Embed health

A bank surfaces its ingest health: embed_ready (embeddings are current), plus docs_failed and docs_warned counts so you can see which documents didn't embed cleanly.

Using a bank with an agent

In Agent Builder, link (or unlink) a Knowledge Bank to an agent; the agent's own bank is auto-injected via the "Search the agent's knowledge base" tool. You can also create an agent directly from a bank (POST /api/knowledge-bases/{id}/create-tool), and clear a bank's contents (POST .../clear).

Before deleting a bank, the platform runs a usage reverse-lookup and warns if agents or tools still reference it (impact-aware delete guard).

Permissions & API

Authoring a Knowledge Bank requires project.edit. Core endpoints (knowledge_bases router):

Endpoint	Purpose
GET /api/knowledge-bases	List banks.
POST /api/knowledge-bases	Create a bank.
POST /api/knowledge-bases/{id}/docs	Upload documents.
POST /api/knowledge-bases/{id}/create-tool	Create an agent/tool from the bank.
POST /api/knowledge-bases/{id}/clear	Remove all documents.

See also

• Agents overview · Agent Tools
• Connectors → Vector stores
• Recipes → embed