Skip to main content

3. Import history

A fresh install starts with an empty signal stream — you only see things that happen after installation. Importing fills in the past so synthesis has something to correlate against from day one.

Open the profile avatar (top right) › Imports to reach the import page. There are two paths there, independent of each other:

  • GitHub History Import — commits, pull requests, CI runs, reviews, issues, and security alerts from your connected repositories.
  • ADR Import — existing Architecture Decision Records in MADR or Nygard markdown format.

You can run both, neither, or one and not the other.

Imports consume your monthly capture quota

Imports are billed the same as live signals. Every backfilled commit, PR, review, and ADR counts as one capture against your plan.

If you've enabled Git commits on the previous page, even a moderately active repo can produce several thousand commit captures from the default lookback window. The Free plan's 500 captures/month limit will be exhausted by a single repo's commit history in most cases.

Recommendations:

  • Evaluating Kleio → import without commits first. PRs + reviews give synthesis enough to demonstrate the loop.
  • Active install → enable commits, but import one repo at a time and watch the capture counter.
  • Large team / many repos → wait for targeted import filters (see below) before backfilling commits at scale.

Imports are append-only — you can't undo one to reclaim quota.

GitHub history import​

On the Imports page, the GitHub History Import card has a single Import GitHub history action. It walks each connected repository and emits the same kind of signals you'd see going forward, with signal_at set to the original event time so the timeline is accurate.

What gets backfilled:

  • Commits on the default branch (only if the Git commits signal is enabled in Configure)
  • Merged pull requests with metadata (author, title, body, labels)
  • PR reviews and review comments
  • CI runs — only if the CI runs signal is enabled
  • Issues opened or closed in the lookback window — only if the Issues signal is enabled
  • Security alerts active in the lookback window

What does not get backfilled:

  • Closed-but-unmerged PRs (low signal density)
  • Issue comments (Kleio doesn't ingest issue threads today)
  • Deployments (forward-only from install time)

Backfill runs asynchronously. Signals stream into the dashboard as it progresses; large repos can take several minutes per repo. You can keep using Kleio while it runs — the import is rate-limited so it won't drown live captures.

Adding repos before importing​

If you want history from repos that aren't connected yet, add them first via Profile › GitHub › Manage repositories (see Configure › Manage GitHub connections) then come back here. The import button always uses the current set of connected repos.

ADR import​

If your team already keeps Architecture Decision Records as markdown in a repo, you can import them as Kleio decisions in one shot. Two formats are detected automatically:

  • MADR — the MADR template with frontmatter (status, date, decision-makers) and the standard ## Context and Problem Statement / ## Considered Options / ## Decision Outcome sections.
  • Michael Nygard format — the original four-section template (## Status, ## Context, ## Decision, ## Consequences).

Each ADR file becomes one decision in your workspace, with:

  • content → the Decision section
  • rationale → the Context + Considered Options sections (combined)
  • confidence → inferred from the Status field (accepted → high, proposed → medium, superseded / deprecated → preserved as historical)
  • decided_at → from frontmatter date if present, otherwise the file's git history first-add timestamp

How to import​

  1. On the Imports page, find the ADR Import card and type the Repository name (org/repo) the ADRs live in.
  2. Select .md files — multi-select the ADR files. Files that don't match either ADR template are skipped with a warning.
  3. Confirm the preview. Each file shows the parsed title, status, and which fields will be populated.

Re-importing the same files is a no-op — ADRs are deduplicated by (repo, file_path, content_hash).

ADR repos are usually small

Even a year of decisions across a large team is rarely more than a few dozen ADRs. ADR import is the one import that effectively never threatens the capture quota — if you have ADRs, you should almost always import them.

Coming soon: targeted import filters​

The current import is all-or-nothing per signal type, across all connected repos and the full lookback window. We're working on filters to let you import surgically:

  • Per-repo selection — pick which connected repos to backfill, instead of all of them.
  • Date-range bounds — "last 30 days" / "since 2026-01-01" instead of the default lookback.
  • Branch filters for commits — default branch only vs. all branches.
  • Author filters — only your commits, only your team, etc.
  • Path filters — ignore monorepo subtrees you don't care about.

Until those land, the safe pattern is: enable signals selectively, import one repo at a time, and watch the capture counter. If you've already burned through a month's quota on an over-eager import, info@kleio.build and we'll sort it out.

You've imported what you want​

With history loaded (or deliberately skipped), you're ready to capture from your terminal and your editor.

→ 4. Install the CLI