Strata

Knowledge Base as Code. Strata turns large reference documents — standards, regulations, internal specs, policy manuals, engineering handbooks, compliance frameworks — into a layered knowledge base that humans review in a pull request and AI agents query for exactly the passage they need.

Nothing about Strata is tied to a domain or an industry. If your organisation has documents too long for anyone to re-read on demand, Strata is for those documents.

• No database, no runtime state. The knowledge base is .yaml and .md files in Git. Review it the way you review code.
• Tables are never rewritten by an AI. They are machine-copied from the source and automatically diffed against the original on every build.
• A query loads a slice, not a corpus. Typical lookups return 1–4 sections instead of a whole document — a few sections' worth of tokens per call, not the document's.

pip install "strata-kb[ingest]"
mkdir my-hub && cd my-hub && git init
kb init --kind hub
kb ingest source/employee-handbook.pdf --id hr-handbook --tags hr,policy
kb summarize     # needs the claude or copilot CLI on your PATH
kb build
git add -A && git commit -m "kb: hr-handbook"   # publish ships committed content
kb publish       # a hub searches only federation/, so it publishes to itself first
kb query "parental leave eligibility"

Contents

The problem · The method · Install · Repo kinds · The lifecycle · Command reference · Guides · Development · License

The problem

Long reference documents share two traits, whatever the field:

Strata attacks both at once:

• Split by section, so a lookup lands on the right passage instead of the right document.
• Tables never pass through a model. Code extracts them verbatim, and kb build diffs every summary table against the original. A table that was altered, dropped, duplicated, reordered or invented fails the build and blocks the change — in both directions.

The method

Four layers: L0 → L1 → L2 → L3

Think of a library lookup stack, coarse to fine: department catalogue → table of contents → chapter summary → full text.

A lookup walks L0 (which documents matter) → L1 (which sections matter — almost free) → L2 (condensed content of the few relevant sections). L3 is opened only when absolute fidelity is required. That is where the token saving comes from: the model never loads what it did not need.

The non-negotiable rule: an AI may write the prose around tables. The tables themselves are always machine-copied at both L2 and L3, and kb build verifies it. Whitespace and alignment differences are normalised (NBSP, tabs, trailing spaces, :-- alignment rows); everything else is compared byte for byte.

Every section has a stable id (5.129, ch2), which is also the citation key. A section is pending until a model writes its summary, summarized after that, and reviewed once a human approves it; approval is a human act and is never automatic. A ticket or spec cites sections in a kb-context block pinned to the hub's commit, so kb resolve can tell you later whether what it cited still says the same thing.

Federation: hub, child, ba, dev

One repo holds the shared, searchable copy; the others author or consume.

   outside documents                 product code
          |                               |
     +----v----+                     +----v----+
     |  child  |                     |   dev   |
     +----+----+                     +----+----+
          | kb publish                    | kb publish (CI: kb ci-publish)
          +--------------+  +-------------+
                         v  v
                    +---------+        read-only
                    |   hub   |<------------------ ba
                    +----+----+        (publishes its own plan)
                         |
              kb query / MCP / Web UI

Each repo publishes its full .kb/ to the hub's federation/<repo-id>/ through a pull request. Merging that pull request is the single gate that makes content searchable. Nothing is searched except what the hub holds. The system design (data model, trust model, topologies) is in the architecture document.

Install

Needs Python 3.11+ and Git.

pip install strata-kb            # kb CLI + MCP server
pip install "strata-kb[ingest]"  # + PDF ingestion (docling)
pip install "strata-kb[embed]"   # + semantic search
pip install "strata-kb[server]"  # + hosting the shared HTTP server and Web UI login
pip install "strata-kb[code]"    # + routes, pages, jobs, symbols in `kb code-ingest`
pip install "strata-kb[s3]"      # + S3 asset offloading

From source:

git clone https://github.com/vuonglq01685/strata-kb
cd strata-kb
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[ingest,dev]"
kb --help

• Git 2.31 or newer on any machine whose hub URL carries a credential (the https://x-access-token:<token>@github.com/org/repo.git shape the CI templates pass in STRATA_KB_HUB). Older git ignores the mechanism that hides the token and every hub command fails with git's own authentication error. An ssh hub:, a public https:// hub and a local-directory hub: carry no credential and need no particular version.
• .kb/config.yaml is committed, so never put a token in hub: — pass a credentialed URL in STRATA_KB_HUB, which overrides the file.
• Docker. kb docker-setup (or /kb-docker-setup) prepares a hub (.env, a generated STRATA_KB_HTTP_TOKEN, docker compose up -d) or a child (pulls the ingest image, so ingestion needs no local Python). A ba or dev repo needs neither. Release tags push ghcr.io/vuonglq01685/strata-kb. The hub's HTTP auth is a bearer token plus local hub accounts — no OAuth or SSO. That is adequate for an internal network and not ready for the public internet.
• Windows is fully supported (every release is gated on windows-latest). kb forces UTF-8 on stdin/stdout/stderr on every OS. If a deep KB tree hits the 260-character path limit, run git config --global core.longpaths true and enable LongPathsEnabled in the registry.

Repo kinds

kb init --kind hub|child|ba|dev scaffolds a repo for its role and records kind: in .kb/config.yaml. Re-running kb init refreshes the scaffold and keeps your .kb/config.yaml and .kb/index.yaml.

Slash commands are scaffolded for Claude Code, GitHub Copilot and Cursor, and the MCP client is wired in .mcp.json and .cursor/mcp.json; each guide lists them and the few that differ per assistant.

ba and dev repos can run unattended (/kb-auto, kb auto). Read the Automation modes section of the BA or Dev guide before turning it on: an unattended run merges its own pull requests with the rights of your gh login (--admin changes nothing) and publishes with no human review, and it needs branch protection on main first; see Automation modes, Security.

The lifecycle

 source PDF ──kb ingest──► sections, L3 full text, L2/L1 scaffold   (machine, no AI)
            ──kb l3 ─────► L3 checked against the PDF               (human, if flagged)
            ──kb summarize► L2 prose + L1 one-liners                (AI fills the blanks)
            ──kb build───► gate: nothing pending, tables match, quality rules
            ── pull request ► a subject-matter expert reads the diff (human)
            ──kb publish─► pull request on the hub; merge = live
            ──kb query / MCP / Web UI──► the 1–4 most relevant sections, with citations

Machines do the mechanical work (sectioning, verbatim tables, integrity checks). AI does the language work (summaries). Humans sign off. No step skips the check that follows it. Source documents never go into Git: they live under source/, which kb init ignores.

Command reference

Every command takes --help. One line per command or group; the guides give the daily use.

Exit codes: 0 success, 1 error (including a misconfiguration), 2 citation stale (and a few command-specific results, listed in the guides), 3 a ticket claim taken or lost.

Guides

One guide per role: who it is for, first-time setup, daily work, automation modes, troubleshooting and a short reference appendix. English first, then Vietnamese; the PDFs are rendered from the same sources.

• Architecture — data model, components, federation, trust model, topologies: EN · VI · PDF EN · PDF VI
• Running the hub as a remote MCP server: docs/deploy-remote-mcp.md
• Release notes: CHANGELOG.md

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[ingest,dev]"
./scripts/gate.sh          # the CI tiers on one interpreter: lint, tests, package checks
pytest                     # tests only

The gate runs ruff check ., ruff format --check . and pyright (T0), the tests (T1), then builds the wheel and sdist and checks them (T2), runs the real user journey from the installed wheel (T3) and the compatibility suites (T4). CI adds ubuntu × Python 3.11/3.12/3.13 and windows-latest.

To release: bump the version in pyproject.toml, run uv lock, commit, and once CI on main is green for that commit push the tag vX.Y.Z. The release re-runs the artifact tiers and the image build and publishes to PyPI and GHCR only when everything is green. To rebuild the PDFs: uv run --extra docs python docs/src/build_pdf.py.

License

Apache-2.0. See LICENSE.