Keep the Company Wiki or Add an Agent-Readable Layer?
Evaluate whether to replace Confluence and Notion or deploy a dedicated agent-readable layer: compare wiki migration scope, human editing workflows, dual-store synchronization, and Model Context Protocol (MCP) integration.
Key takeaways
- Compare three viable paths: improve the current wiki, move to a platform suited to both people and agents, or add a governed knowledge layer alongside the wiki.
- Start with the workflow: define who authors and approves information, what agents must read or change, which source is authoritative, and what permissions must carry through.
- Measure the outcome: test grounded answers and task success against a current-state baseline, including refusals, permission boundaries, updates, deletions, and operator effort.
- Treat coexistence as an operating model: assign authority by content class, preserve source identity and revision lineage, and specify how changes, failures, withdrawals, and access revocations propagate.
- Do not mistake a protocol or format for governance: MCP can connect tools, but does not by itself guarantee portability, permission inheritance, fresh context, or change notifications.
Choosing knowledge infrastructure is a workflow and governance decision, not a contest between “human” and “machine” formats. An existing wiki may already provide version history, APIs, native AI, or external agent connections. Replacing it can also be reasonable when another platform meets both people’s authoring needs and agents’ access requirements. A separate knowledge layer is useful only when it solves a specific gap that the current platform or a replacement cannot address at acceptable operating cost.
Three practical architecture choices
The right choice depends on the work people and agents actually do. Confluence, for example, documents page version history and Rovo agent knowledge sources; Notion documents MCP connections that can read and write pages. These are capabilities to evaluate in the specific deployment, not proof that every workflow or permission model is covered. See Confluence page history, Rovo knowledge sources, and Notion MCP.
| Option | What it means | Potential advantages | Questions and costs to validate |
|---|---|---|---|
| Improve the existing wiki | Keep the current platform; tune information architecture, ownership, approvals, APIs, native AI, or agent connections. | Avoids a broad content move; keeps familiar authoring and review workflows; may use existing history and access controls. | Can agents find authoritative material and perform the required reads or writes? Do permissions map correctly? Are search quality, administration, and vendor costs acceptable? |
| Replace it with a people-and-agent platform | Move to a platform selected for the full authoring, collaboration, governance, and agent workflow—not just its storage format. | Can simplify architecture if the new platform meets human editing and agent integration requirements in one operating environment. | Validate coediting, approval, history, APIs, data export, permissions, agent access, migration effort, training, and exit options. Replacement does not have to mean Git-only documentation. |
| Add a separate knowledge layer | Keep the wiki for some work and operate a second system for selected, governed agent context. | Can support different retrieval, structure, or integration requirements without replacing every human workflow. | Adds curation, synchronization, permissions, monitoring, incident response, and another system to pay for and operate. Define which system is authoritative for each content class. |
No option guarantees better retrieval or lower cost on its own. Compare the same representative tasks and users across the current setup and the proposed alternatives before committing to a migration or second store.
Decide from evidence, not format labels
Write down the workflow before choosing an architecture. For each use case, answer:
- Users and tasks: Who asks the agent for information, and what decisions or actions follow? Include non-technical authors, reviewers, operators, and people whose access differs.
- Authoring and approval: Where are drafts created? Who approves a policy or operational instruction? Is collaborative editing, comment history, formal approval, or a published effective date required?
- Agent access: Does the agent only search and cite, or must it create or update content? Which client, API, native AI feature, or MCP server is involved? What write actions require review?
- Authority and provenance: For each content class, which system owns the approved version? Can the agent identify its source, owner, revision, effective state, and supersession history?
- Permission mapping: Are permissions checked for the requesting user at retrieval and action time? How do group membership, inherited access, revoked access, and service identities behave across systems?
- Retrieval quality: Can the system return the right approved passage with a traceable source, and abstain when evidence is missing or access is denied?
- Operations and cost: Count subscriptions and infrastructure, migration and integration work, content review, connector maintenance, security administration, support, and the cost of handling failed or stale synchronization.
A wiki’s tables, attachments, meeting notes, or working documents may be important evidence. Include or exclude them according to purpose, authority, and the task being tested—not through a blanket rule that all notes are irrelevant. Likewise, converting rich content to Markdown changes representation; it does not validate meaning or guarantee that tables, attachments, relationships, and access rules survive the conversion.
Run a bounded pilot against the current baseline
Before selecting an architecture, run a limited pilot with one team, one defined content class, and a fixed set of representative questions or tasks. A short, pre-agreed window—such as two to four weeks—can be enough to expose workflow and operating issues; it is a planning example, not a performance benchmark.
- Record the baseline: Run the same tasks using the current wiki and current agent workflow. Save the source material, prompts, outputs, citations, access context, and time spent by operators.
- Compare equivalent candidates: Test the improved wiki, replacement platform, or additional layer against the same task set and user permissions. Keep the model and task conditions as consistent as practical, and document unavoidable differences.
- Score outcomes: Check whether answers are grounded in the authoritative version, whether the requested task succeeds, whether unsupported answers are refused, and whether citations lead to the relevant source. Set acceptance thresholds before seeing the results, based on the risk of the workflow; do not borrow a universal score.
- Exercise change and access events: Update a source, withdraw or delete it, and revoke a user’s access. Verify what happens in search indexes, caches, connected clients, generated derivative material, and any agent actions. A freshness target is not permission to serve data after its access has been revoked.
- Count operator work: Track setup, review, correction, synchronization, permissions, failed jobs, retries, and incident handling. Include this effort in total operating cost rather than treating it as free.
- Make a decision: Keep the current wiki, replace it, or add a layer only if the measured benefits for the target workflow justify the migration and recurring operating burden.
The pilot should include both normal and failure cases: ambiguous or conflicting sources, missing evidence, unauthorized requests, an update during the test, a failed synchronization, a deletion, and a permission revocation. The point is to learn how the actual system behaves, not to assume a particular result.
If you add a layer, make authority and change flow explicit
A dual-system design can work when each system has a clear role and its boundaries are maintained. Before moving content, create a content-class register that names the authoritative system, responsible owner, approval path, and consuming workflows. For every copied or transformed item, preserve at least the source ID, source revision, owner, effective state or date, and lineage back to the source. A title or a Markdown file alone is not sufficient provenance.
For each content class, choose one of these operating rules:
- Controlled one-way flow: The source system remains authoritative. An approved change is reviewed, transformed, and published to the agent layer. Changes made in the destination do not silently overwrite the source.
- Explicit conflict rules: If edits must flow in both directions, document which system wins for each field or state, how conflicting edits are detected, who resolves them, and how the resolution is recorded. Do not rely on an informal expectation that the stores will “stay in sync.”
Assign named responsibilities for content approval, transformation, synchronization, access review, and incident response. Define idempotent retries, visible failure alerts, a queue or other recovery path for unprocessed changes, and an owner for resolving stuck updates. Test deletion and withdrawal as first-class changes: remove or suppress the material in downstream indexes and caches, revoke derived access, and identify derivative documents or summaries that may need removal or regeneration. Record evidence that the change reached each relevant destination.
A freshness window is useful for setting operational expectations, but it is not an authorization rule. Permission revocation and withdrawal need their own handling and should block access according to the system’s security requirements, even if an index has not completed its next routine refresh. Keep a way to stop retrieval or writes while a broken synchronization path is investigated.
When normalizing source material, validate meaning as well as syntax. Preserve tables, attachments, and their relationships when a task depends on them; retain access checks for linked files; and record what was omitted or transformed. Markdown conversion is a transport or representation step, not semantic review, policy approval, or permission validation.
MCP connects tools; it does not define your governance
MCP is one integration option for exposing context or actions to compatible clients. Notion documents an MCP connection that can read from and write to its workspace, while Atlassian documents its MCP server for accessing and interacting with Atlassian data. Review the deployment-specific product documentation for supported operations, authentication, administration, and permissions: Notion MCP, Atlassian MCP server, and adding an external MCP server to Atlassian Administration.
MCP alone does not make two systems fully portable or guarantee that a client receives current context, inherits the source system’s access controls, or subscribes to changes. The protocol specification describes resource notifications as capability-dependent and leaves resource use to the host application. Verify the actual server and client behavior, identity propagation, tool scopes, caching, and failure handling in your deployment. See the MCP resources specification.
A separate layer should therefore be justified by a requirement—such as a needed governance boundary, content model, or integration workflow—that the current platform cannot meet adequately. MCP availability by itself is not a reason to add another store.
Where AKB may fit
The current AKB project README describes AKB as a PostgreSQL-native knowledge base with native revision history and explicit support for legacy Bare Git installations. It documents documents, tables, files, and relations, with a Web UI, REST API, and agent-facing MCP tools. Treat ingestion, curation, approval, and synchronization with another wiki as separate design and operating work unless your chosen deployment explicitly provides and configures those workflows; the README describes the core as a read/write knowledge store rather than a built-in approval or synchronization guarantee.
FAQ
When should we keep and improve the current wiki?
Keep it when it meets the authoring, approval, history, permission, and agent-access needs of the target workflows at an acceptable total operating cost. First test whether better ownership, scoped knowledge sources, existing APIs, native AI, or an approved external connection closes the actual gap. Do not migrate solely because the content is not already in a machine-oriented format.
When is an additional knowledge layer worth its cost?
Consider one when a defined content class or agent workflow needs capabilities the current platform does not provide adequately, and a replacement would disrupt necessary human work. Compare the expected benefit with recurring curation, synchronization, access-control, monitoring, recovery, and support effort. If no owner can operate the second system and its change flow, the added layer may create more risk than value.
How do we prevent authority conflicts and knowledge drift?
Name one authoritative system for each content class, then preserve source identity, revision, owner, effective state, and lineage in every downstream copy. Define controlled one-way publication or explicit conflict-resolution rules, assign reviewers, monitor failed updates, and test withdrawal, deletion, and permission-revocation propagation. Never assume that a successful Markdown conversion or a recent index timestamp proves the content is approved or authorized.
Does MCP automatically carry over permissions and keep agent context current?
No. MCP provides an integration protocol, not a universal permission or freshness guarantee. Product integrations may enforce their own access rules, but you still need to verify which user or service identity is used, what tools can read or write, how revocation is enforced, what is cached, and whether resource-change notifications are supported by both the server and client. The MCP resources specification makes subscriptions optional capabilities.
How should we decide whether a pilot passed?
Set risk-based acceptance criteria before testing. Compare the same representative tasks against the current baseline; check grounded answers and task completion, citations to the authoritative revision, appropriate refusal for missing or unauthorized information, and safe handling of writes. Also verify update, delete, withdrawal, and access-revocation propagation through indexes, caches, and derivative content, then count operator effort and recurring cost. There is no universal score that substitutes for criteria tied to your workflow.
Evaluate Your Knowledge Architecture
Compare your current wiki, a replacement platform, and any proposed additional layer against the same user workflows, permission tests, retrieval tasks, and operating costs.