Knowledge as infrastructure
Most AI platforms treat knowledge as a prompt injection problem. Paste your docs, chunk them, hope the embeddings find something useful. That works for demos. It falls apart the moment you have two teams, three tools, and a compliance requirement.
The copy-paste model
The simplest version of an AI knowledge base looks like this. Paste your text into a box, click embed, ask questions. You paste your refund policy, ask "what is the refund window?", and the answer comes back correct. Sold.
Now try it with real data. Your Confluence has 4,000 pages across 12 spaces. Your engineering team writes ADRs in GitHub. Your support team keeps runbooks in Notion. Nobody is going to paste 4,000 pages into a text box.
The paste-and-embed model assumes knowledge is static, small, and lives in one place. In practice, knowledge is distributed, constantly changing, and owned by different teams with different access rules.
What goes wrong with flat knowledge
A single vector index per workspace is the simplest starting point. Every document gets chunked, embedded, and dumped into the same bucket. When a query comes in, the system searches the entire bucket and returns the top chunks by cosine similarity.
I think this will break down faster than people expect.
An engineering workspace has both API documentation and HR onboarding guides indexed. Someone asks "what is the timeout policy?" and gets back the employee probation period instead of the HTTP request timeout. Both contain the word "policy" and "timeout". The embeddings see similarity. The user sees nonsense.
I do not think better embeddings or a bigger context window will fix this. The problem is structural. Knowledge needs boundaries, ownership, and access control before it ever touches a vector database.
A three-layer problem
I keep landing on the same three-layer pattern across different parts of SupaProxy, whether it is guardrail policies, workspace routing, or composable packages. For knowledge, the layers are connect, sync, scope.
Connect (plugin layer)
- One plugin per knowledge source (Confluence, Notion, GitHub). Handles authentication, API quirks, rate limits.
- The plugin developer writes this once. Every organisation that installs it gets the same capability.
Sync (organisation layer)
- The admin chooses what to sync, which spaces, which folders, how often.
- Engineering syncs architecture daily. Legal syncs contracts weekly. HR might exclude their entire space.
Scope (workspace layer)
- Each workspace selects which synced sources it needs. Payments gets API docs. Onboarding gets HR guides.
- No workspace sees the entire organisation dumped into one index. Focused retrieval, less noise.
Connection is a plugin problem. Sync is an organisation problem. Scope is a workspace problem. I suspect that mixing these layers is where most knowledge base confusion comes from.
Why the plugin developer matters
A generic "connect to anything" adapter sounds appealing. Fetch a URL, parse the HTML, chunk the text. It handles the easy cases and butchers the rest.
Confluence pages have macros, nested tables, and embedded diagrams. GitHub repos need different chunking strategies than prose. Notion databases have structured fields that lose all meaning when flattened to text.
The person who understands Confluence best is the person building the Confluence plugin. They know that labels matter for filtering, that child pages should be chunked together with their parent, and that the storage format XML needs specific handling that generic HTML stripping will destroy.
This is why I want the plugin contract to give developers control over the full pipeline. What units are available to sync, how to fetch content, and what options to surface for the admin. The platform handles authentication, scheduling, embedding, and storage. The plugin handles the source-specific intelligence.
Sync is not a one-time import
A one-shot import breaks within days. Someone updates a Confluence page, and the AI keeps answering with the old version. The knowledge base is stale before anyone notices.
Sync needs to be continuous, configurable, and observable. The admin sets a frequency. The system tracks what changed since the last sync. Content hashes detect updates without re-embedding unchanged chunks.
Every knowledge source has different change detection capabilities. Confluence has last-modified timestamps. GitHub has commit history. Some APIs have webhooks. Some have nothing, and you have to re-fetch everything and diff locally. The plugin developer knows which approach works for their source. The platform provides the scheduling and status tracking.
The policy layer
Legal documents should not appear in customer support contexts. Salary data should not be retrievable by engineering workspaces. Draft policies should not be treated as authoritative.
The org-level sync policy is the first line of defence. The admin defines what is allowed and what is excluded. Workspace-level source selection is the second line, each workspace chooses only what it needs. Less noise means better retrieval.
Neither is a substitute for proper access control within the source itself. If a Confluence space has restricted permissions, the sync respects those permissions. The plugin reads what the authenticated account can read. The platform does not escalate access.
Open questions
I do not have all of this built yet. The architecture feels clear, but the implementation raises questions I am still working through.
How should sync handle token budgets? Embedding 4,000 Confluence pages is not free. Should the system prioritise recently updated content? Should it de-prioritise pages that are never retrieved?
How granular should workspace scoping be? Space-level or page-level? A single Confluence space might have 500 pages, and only 20 are relevant to a specific workspace. Plugin-side filtering is more flexible. Platform-side filtering is more consistent.
How do you handle conflicting information across sources? If the Confluence page says the refund window is 30 days and the Notion runbook says 14 days, which one wins? That is not a retrieval problem. It is a governance problem.
These are the kinds of questions that only surface when you treat knowledge as infrastructure instead of a context window.