ADR-0005: Knowledge as a Separate Service with an MCP Interface¶
- Status:
Accepted
- Date:
2026-10-01
Note
Since ADR-0027: Tenancy Model — Platform, Organization, Project, customers are called organizations and the installation-wide level formerly called the organization is the platform; this record keeps the terms of its time.
Context¶
Knowledge (documents, decisions, notes, debt, lineage) is the long-term memory that makes fresh-agent onboarding work. It is the most confidential data Ballet holds, must be isolated per customer, and is consumed primarily by agents. It changes on a different cadence from the tracker and may later need different storage (vector search).
Decision¶
Knowledge is a separate Go service with its own database. Agents use it through an MCP server (search, read, write, lineage); the UI uses a REST API. It references tracker entities only by ID and trusts Core-issued tokens for identity and customer scope, enforcing the scope on every call.
Alternatives Considered¶
Store knowledge in the git repository¶
Advantages:
Versioned with code.
Disadvantages:
No cross-project lineage; not searchable across repos; ties knowledge to one host.
Decision Criteria¶
Security isolation, independent evolution, agent accessibility, operational cost.
Rationale¶
A separate service and database give a physical boundary for the most sensitive data and let the knowledge model evolve independently. MCP is the native interface for all supported agent runtimes.
Consequences¶
Positive¶
Isolation enforced in one place; database can be secured separately.
Negative¶
Cross-service consistency (e.g. ticket deleted, links remain) must be handled explicitly.
Risks¶
Lineage queries need both tracker and knowledge data; the boundary must be designed so Knowledge stores enough link data to answer them.
Follow-up¶
Design the knowledge data model and MCP tool set.