Concepts

Knowledge organizes your team's decisions, constraints, and standards into five core entities. This page explains what each one is, why it exists, and how they work together.

Scopes and Namespaces

Scopes organize knowledge by domain. Namespaces subdivide scopes for finer-grained structure.

A scope represents a domain or department — Engineering, Product, Operations, Security, Legal. Each scope contains its own decisions, invariants, rules, overrides, and events.

Namespaces subdivide a scope into sub-domains. Every scope starts with a global namespace. You can create additional namespaces to organize entries by team or area. Namespaces support up to two levels of nesting (e.g. payments/stripe).

API keys control access at the scope level: no access, reader, contributor, or admin.

Tenants represent organizations. Each tenant has its own scopes, entries, and API keys. Isolation is strict — a key from one tenant cannot access another tenant's data.

Decisions

A decision records what was decided, by whom, when, and why — as an immutable historical fact.

"We chose PostgreSQL for all transactional data stores. We evaluated PostgreSQL, DynamoDB, and CockroachDB. PostgreSQL won on ACID guarantees without distributed complexity."

Decisions capture four things: what was decided, the context that led to it, the reasoning behind the choice, and who made it (human, agent, or system).

Decisions are immutable — once created, they cannot be modified. If a decision is later revised, the new decision links to the old one via a supersedes relation. This preserves the full history of how thinking evolved.

Decisions can be created from the dashboard, the API, or by an AI agent via MCP (e.g. "Record a decision: we chose Playwright for E2E testing").

Why decisions matter

Without recorded decisions, teams spend time re-debating settled questions. New hires don't know why things are the way they are. Knowledge makes the reasoning searchable and permanent.

Best practices

• Record at decision time not retroactively — context and reasoning are freshest when the decision is made.
• Include the alternatives considered — "We evaluated X, Y, and Z" is more valuable than "We chose X."
• Link to constraints — if a decision creates a rule or invariant, link them so the reasoning is traceable.

Invariants

An invariant is an absolute constraint — something that must never be violated. Invariants are the strongest enforcement mechanism in Knowledge.

"All public API endpoints must require authentication."

Invariants are blocking: if an action conflicts with an active invariant, Knowledge reports a blocking conflict. The action should be stopped or an override must be obtained.

How invariants are enforced

Invariants are checked at three points:

• Compliance check— an agent or human tests an intended action against the registry. If it conflicts with an invariant, Knowledge returns a blocking result.
• CI Compliance Check— the AI agent reads the PR diff and checks it against active invariants. If the diff conflicts with an applicable invariant, the agent reports a violation and the pipeline fails.
• MCP Agent— the agent queries invariants before acting. If a conflict is detected, it stops and reports, or requests approval.

Approval-gated invariants

Some invariants are too critical for anyone to bypass silently. When requires_approval is enabled, an exception requires human approval:

1. Agent detects conflict with invariant
2. Agent requests approval (with justification)
3. Human reviews in the dashboard (or via Slack notification)
4. If approved → an override is auto-created
5. Agent re-checks → conflict resolved → proceeds

This ensures human oversight for the most critical constraints.

Best practices

• Keep invariants few and critical — if everything is an invariant, nothing is. Reserve them for constraints that should genuinely never be violated.
• Write clear rationale — explain why the constraint exists, not just restate it.
• Review periodically — invariants that no longer apply should be revoked, not left as noise.

Rules

A rule is an active directive — a statement of what should be done. Unlike invariants (absolute blocks), rules can be mandatory or advisory, and they are versioned to track how standards evolve.

"All PRs must be reviewed by at least one team member before merging."

Severity levels

Versioning

Rules change over time. When a rule is updated, Knowledge creates a new version while preserving the full history. Each version records who changed it, when, and why — your audit trail for how standards evolved.

For example, a rule might start as "All PRs must be reviewed by one team member" and later become "...by two team members" after a production incident. Both versions are preserved.

Best practices

• Distinguish mandatory from advisory — not every guideline needs to block CI.
• Version with change reasons — a version without a reason is an incomplete audit trail.
• Keep directives actionable — "Code should be clean" is not enforceable. "All functions must have explicit return types" is.

Overrides

An override is a governed exception to an invariant or rule. It documents that the organization knowingly deviated from a constraint, with justification and conditions.

"Health endpoint must be public for load balancer checks. Only applies to /health and /ready endpoints. Expires 2025-06-01."

Overrides are not workarounds. They are explicit, documented exceptions that prove the organization acknowledged a constraint, evaluated the risk, and decided to deviate — with a clear paper trail.

Temporary vs. permanent

Prefer temporary overrides. Permanent overrides should be rare and well-justified.

How overrides affect compliance

When an override is active, the compliance check moves the target entry from "conflicts" to "overridden." The action is allowed, but the override is visible — it's not silent. The CI compliance check also recognizes overrides.

When an invariant has requires_approval enabled, overrides are created automatically after a human approves the exception through the approval workflow.

Best practices

• Always include justification — an override without justification is a gap in your audit trail.
• Use conditions — "Only applies to /health endpoint" is more precise than overriding the entire invariant.
• Review expired overrides — they may indicate constraints that need updating.

How They Work Together

Links connect them into a navigable graph of organizational knowledge.

For API details, see the Integrations page (requires login).