Skip to content
db-cluster

db-cluster Handbook

db-cluster is an AI-native federated database cluster. Four specialized truth stores — canonical, artifact, index, ledger — behaving as one governed substrate, with typed errors, mutation receipts, and MCP / SDK / CLI surfaces.

This handbook is the canonical operator + developer + AI-integrator guide. The CLI --help is the source of truth for flags; this handbook is the source of truth for why and how.

Who this handbook is for

Section titled “Who this handbook is for”
  • AI agents consuming the MCP surface — cluster_find_sources, cluster_retrieve_bundle, cluster_propose_mutation, etc. — and needing to branch on structured AiErrorEnvelope responses.
  • Operators running the cluster locally or with a Postgres canonical backend, who want typed exit codes, doctor / verify diagnostics, and safe backup / restore.
  • Developers embedding db-cluster as a library via import '@mcptoolshop/db-cluster/sdk' and the PolicyEnforcedKernel surface.

What’s in this handbook

Section titled “What’s in this handbook”
PageAudienceWhat you’ll find
Getting StartedAllInstall + 5-minute golden path (init → ingest → retrieve → mutate → trace).
ArchitectureAllThe four-store federation thesis. Why the kernel routes and the cluster owns.
OperationsOperatorsdoctor, verify, rebuild, backup, restore. Runbooks per typed-error class.
Policy & RedactionAllPrincipal, Capability, Policy, TrustZone, VisibilityRule. Redaction at every read path.
MCP IntegrationAI agents16 tools with safety annotations. AiErrorEnvelope shape. Tool catalog.
SDK ReferenceDevelopersClusterSDK constructor, mutation lifecycle, retrieve / trace / why.
CLI ReferenceOperatorsFull command list. Exit-code table. --quiet / --log-level / --no-color.

Architecture in one diagram

Section titled “Architecture in one diagram”
  CLI / SDK / MCP                       ← surfaces (red, green, cyan colorized)
        │
  PolicyEnforcedKernel                  ← policy + redaction (the root's createSafeCluster handle)
        │
   ClusterKernel                        ← routing, retrieval, mutation lifecycle
        │
  ┌─────┼──────┬──────────┐
  │     │      │          │
Canonical Artifact Index Ledger         ← stores (owner truth vs derivative index)
(Postgres  (local) (local) (local)
 or local)

Core invariants

Section titled “Core invariants”
  1. Every fact has an owner store.
  2. Indexes are derivative — can be deleted and rebuilt from owned stores.
  3. AI never mutates raw state directly — every mutation crosses a typed command boundary.
  4. Every answer traces to source truth via the ledger.
  5. Artifact truth is immutable by default — corrections create versions, not overwrites.
  6. Kernel routes; cluster owns.

Next steps

Section titled “Next steps”