OrbitKB

OrbitKB is an MCP knowledge layer that gives coding agents the smallest useful, evidence-backed view of a software change before they edit code.

It indexes one or many repositories into a cumulative SQLite knowledge base, then answers questions such as: “What needs to change to add feature X?” Agents receive bounded impact, flow, contract, dependency and risk context instead of searching a whole repository or loading unrelated documentation.

Why use it?

Large systems make seemingly small changes expensive to understand. A new feature can cross an HTTP endpoint, application flow, database, broker, another service and an external partner. The relevant knowledge is normally fragmented across source files, repositories and people.

OrbitKB turns that into progressive, queryable context:

1. It extracts deterministic facts locally from source.
2. It stores concise service and contract knowledge with provenance.
3. An agent asks for a compact change briefing, then drills into only the endpoints, flows or dependencies that matter.
4. After delivery, Git-based verification and feedback can measure whether the predicted change surface was useful.

The result is not “more context”; it is less irrelevant context and a clearer record of what is known, inferred, stale or still unknown.

Quick start

Install the CLI:

pip install orbitkb
# or, for an isolated executable:
pipx install orbitkb

Add the tokens extra (pip install "orbitkb[tokens]") for a reproducible tiktoken:o200k_base token-budget measurement instead of the approximate default.

Index a repository, ask for a bounded implementation briefing, and inspect it with an MCP client:

orbitkb index /path/to/shop --repository-name shop --backend codex

orbitkb context "Add Pix as a checkout payment method" \
  --repository shop \
  --max-services 3

orbitkb serve --backend codex

Every command has runnable help:

orbitkb --help
orbitkb index --help

The core workflow is index → ask → verify.

# After the implementation has landed, compare the predicted surface with Git.
orbitkb verify <run-id> --repository shop --since <commit>

Connect an MCP client

Register orbitkb serve as a stdio MCP server. A generic client configuration looks like this:

{
  "mcpServers": {
    "orbitkb": {
      "type": "stdio",
      "command": "orbitkb",
      "args": ["serve", "--backend", "codex"]
    }
  }
}

Use the absolute executable path if orbitkb is not on the PATH inherited by the MCP client. Indexing and change-surface synthesis require an authenticated supported headless backend. Read-only inspection of an existing database does not.

What an agent can ask

Start broad, then narrow the request.

All MCP responses are structured JSON and use progressive disclosure: list a bounded set, select one item, then ask for detail. The full per-tool contract — exact response fields, pagination and filtering rules, ambiguity handling, and every plan_change review-unit and find_architecture_smells finding this table's tools can return — is documented in INTERFACE.md.

What OrbitKB knows

OrbitKB keeps three kinds of information separate:

Unknown or ambiguous data stays explicit. OrbitKB does not choose an implementation candidate silently, turn missing configuration into proof, or present an architecture smell as a production defect.

Source coverage

The supported deterministic subset is intentionally focused:

An optional external depth provider can enrich a selected flow when native resolution is insufficient. It is bounded by timeout, edge budget, validation, cache and a local circuit breaker; it never injects an opaque whole-repository graph.

Cumulative knowledge across repositories

One database can accumulate independent repositories or a monorepo:

orbitkb index /work/checkout --repository-name checkout --backend codex
orbitkb index /work/payments --repository-name payments --backend codex
orbitkb list

A service identity is (repository, name). When names collide, agents must pass the repository to service-scoped tools. This avoids silently mixing two services named orders from different repositories.

Re-indexing is authoritative for detected service boundaries. Removed services are removed from the knowledge base; moved services keep their identity by name, while a renamed service at the same root keeps its identity by root path. Repository removal is explicit:

orbitkb remove --repository retired-service

Safety and data handling

• Source and configuration evidence is redacted before generation, storage, logs and embeddings.
• Security findings retain locations and remediation, never secret values.
• Context-budget telemetry stores only metadata such as service IDs, counts, response size and a token estimate; it never stores task text, prompts, source or cards.
• Telemetry failures are non-blocking.
• Runtime ingestion accepts only normalized edge counters and rejects payloads and tracing attributes.

Feedback closes the loop without retaining sensitive text:

orbitkb context-feedback <run-id> insufficient --missing-services fraud-service
orbitkb context-metrics
orbitkb context-verify <run-id> --repository shop --since <commit>

The compact-context cap remains 1–5 service cards until historical evidence supports a different policy.

Operations

The default database is ~/.orbitkb/orbitkb.db. Pass --db <path> to use another knowledge base.

Back up before destructive maintenance:

orbitkb backup --out /safe/orbitkb-backup.db --db /path/orbitkb.db
orbitkb restore /safe/orbitkb-backup.db --db /path/orbitkb.db

SQLite backup and restore use its consistent backup API. Indexing is serialized per (repository, service); a concurrent attempt fails fast and a lock from a terminated local process is recovered on the next attempt.

Production readiness

OrbitKB is suitable for controlled production use when its support boundaries are accepted and the target environment is validated. It is not an unconditional production approval out of the box.

make readiness-audit

The audit verifies deterministic static and change-surface candidate corpora, then returns "status": "conditional". The remaining conditions are intentional:

• Run the opt-in container E2E in the target Docker or CI environment.
• Validate change-surface predictions against actual Git changes in representative repositories.
• Use the supported SQLite deployment model.
• Profile representative repositories before adding an AST cache or parallel index traversal.

The audit output contains only results and conditions; it does not include source, prompts or secrets.

Development and verification

From a source checkout:

pip install -e ".[dev]"
make verify

Useful focused checks:

make evaluate-static
make evaluate-change-surface
make benchmark-scale
make integration-containers
make readiness-audit

make integration-containers starts ephemeral RabbitMQ, Postgres, MongoDB and LocalStack containers, runs native operations against each (a real SQS create-queue/send-message/receive-message round-trip for LocalStack), and checks representative static contracts. It is opt-in locally and runs in CI. It is an infrastructure smoke E2E, not a benchmark of a user's application or driver compatibility.

make benchmark-scale reports median analysis time and peak traced Python memory for generated Go handler corpora. For a comparable local baseline, change its inputs:

make benchmark-scale SCALE_FILES="5000" SCALE_REPEAT=5

Incremental indexing skips unchanged LLM-derived units by file hash. Static analysis also stores a versioned digest of every local artifact it reads (stack source files, OpenAPI, Protobuf and supported migrations) and skips AST parsing, flow replacement and reconstruction when that digest is unchanged. It still reads those inputs to calculate the digest. --force, external depth enrichment, or a source change during analysis bypasses or withholds snapshot reuse, preserving correctness over speed.

Architecture rules have fact-mutation tests for cycles and fan-out (both at service level and their intra-service component analog), shared storage, read-entrypoint side effects, RabbitMQ recovery-policy hypotheses, cloud dependencies undeclared in IaC (or declared but unreferenced in code), and cloud security/misconfiguration smells (missing dead-letter queue, public object storage, missing encryption or bucket versioning). A component-level cycle or fan-in/fan-out finding is scoped to one service's traced entrypoint-to-boundary flow_edges, never a claim about that service's whole code graph. Static and change-surface evaluations are deterministic regression checks; they do not claim to measure an LLM's judgment on arbitrary codebases.

Further reading

• MCP interface contract