Knowledge sources & connectors
A connector is a Kamiwaza-managed adapter to an external source — a docs site, a wiki, a tracker, a code host. Connectors are how the shared corpus gets its content.
Discovery is dynamic
Kaizen does not carry a fixed connector catalog. It discovers connector instances and their declared surfaces from the current workroom at runtime.
Every chat agent can call the request-scoped catalog to answer what it can use. An agent with an empty connector allowlist receives an empty catalog rather than losing the catalog tool itself. This makes “none authorized” distinguishable from a discovery failure without exposing any connector content operation.
This matters operationally: a new connector type appears in Kaizen without a frontend release and without a Kaizen configuration change. Nothing in Kaizen's compose file or environment enumerates connector types, and nothing should be added that does — hardcoding a catalog would reintroduce the release coupling this design removes.
Identity flows through, always
Every connector call runs as the signed-in member. The provider and Kamiwaza apply that member's current access, which means:
- two members running the same query legitimately get different results;
- Kaizen never holds a broad service credential that could see more than any individual;
- revoking someone's access at the provider takes effect at their next call, not at the next reindex.
There are two readiness shapes:
| Kind | Ready when |
|---|---|
| Service-token connectors | Ready for the whole workroom, with no per-user Connect action |
| User-authorized connectors | Ready only after that user completes the platform connection flow |
Two ways content reaches retrieval
Live retrieval
The connector is consulted during a turn. Access is evaluated again on every turn, so results are always current and always scoped to the asker.
The first live query is federated across every ready surface allowed by the agent's connector policy. The member can name a product, folder, or file as they know it; Kaizen does not first map that wording to a hardcoded provider type. Search-capable surfaces receive the query directly. When a hierarchical surface requires a scope, Kaizen performs a bounded walk of its generic browse contract and retries within the opaque containers the connector returned. Scoped search and browse remain complementary: a successful search with no matches does not assert that a container has no relevant descendants. Folder matches remain useful results even when they have no fetchable document body.
Kaizen-owned sync
A signed-in member can start a sync. Kaizen walks the same generic surfaces and streams each discovered document into the private index immediately.
Progress reporting reflects how the walk actually works: discovery shows an indeterminate count while content fetch, chunking, and embedding run concurrently. Once the walk establishes the final total, the same run switches to exact percentage progress.
Each embedding request retains the initiating member's platform authorization.
The packaged topology runs two document-embedding lanes concurrently so the
reference platform's authorization hop retains headroom. A 403 remains
terminal; Kaizen never substitutes a broader identity to finish the sync.
Synced chunks carry an opaque member/workroom/connector grant that Kaizen revalidates against Kamiwaza on every retrieval. A synced chunk is not a stored permission; it is a pointer that has to prove itself again each time it is used.
Administration
Administrators choose, per discovered instance:
- whether it is exposed as a direct tool an agent may call, and
- whether it participates in RAG as a retrieval source.
Those are independent choices. An instance can be a tool without being indexed, indexed without being a tool, both, or neither. See Connectors administration.
The generic surface contract
Kaizen walks connectors through a generic surface contract rather than per-connector special cases. A connector declares its surfaces; Kaizen consumes them uniformly.
The contract is deliberately typed. Kaizen reads a node's content handle and node type from the platform's serialization rather than assuming a shape — which is what allows any conforming connector to work without a Kaizen code change.
Container identifiers and content-query fields are opaque. Kaizen bounds and round-trips them but never interprets a provider-specific key. This applies to both federated retrieval and the precise per-instance browse/search/fetch tools.
See Building a connector.
Untrusted by construction
Connector content is untrusted input. It is text from systems Kaizen does not control, and it may contain instructions aimed at the model.
Kaizen's answer is structural rather than heuristic: connector content can never become authority. It arrives as evidence, is subject to citation discipline, and cannot grant a tool, widen a scope, approve an action, or alter the authority bundle. A prompt-injection payload can change what a model says; it cannot change what the backend permits.
See Threat model summary.
Failure behavior
If a connector is unavailable, retrieval degrades rather than failing. The federated query reports failed and partially traversed surfaces and returns what the remaining providers authorized. An agent turn continues with the folders, files, and evidence it could gather.
Degrading is not the same as going quiet. A failure keeps the status the platform returned, so a permanent denial never reads as a transient outage. The failures the platform gave no status for stay separated too: an unreachable service, an answer Kaizen could not read, and a call Kaizen never managed to make each carry their own wording rather than collapsing into one message or an invented status code.
An unreadable catalog is the widest of these. It costs the member every browse, search, fetch, and federated-query tool for that turn while leaving the catalog tool in place — which looks exactly like a member who has connected nothing. So Kaizen logs a warning naming the status and whether the payload was unreadable, and an operator can tell the two apart.
Kaizen never substitutes a broader identity to work around a connector authorization failure.