# How the ai-memory Bootstrap Command Imports Existing Project History

> Learn how the ai-memory bootstrap command imports existing project history. It collects git commits and docs, prunes them for LLM token limits, and generates wiki pages.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-19

---

**The `ai-memory bootstrap` command imports existing project history by walking the local repository to collect git commits, README files, and documentation, pruning the results to fit LLM token budgets, and POSTing the bundle to a server that uses an LLM to generate wiki pages.**

The `ai-memory bootstrap` command is the entry point for bringing an existing codebase's institutional knowledge into the ai-memory wiki. According to the `akitaonrails/ai-memory` source code, the process follows a strict three-stage pipeline that balances comprehensiveness against LLM context limits. This article breaks down exactly how the bootstrap workflow collects, budgets, and transforms your project's historical artifacts into a searchable knowledge base.

## Stage 1: Local Source Collection

The bootstrap workflow begins on the developer's machine inside [`crates/ai-memory-consolidate/src/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/bootstrap.rs). The `collect_sources` function (lines 92–108) discovers the repository root via `discover_repo_root` or `discover_main_repo_root`, falling back to the current directory when no `.git` folder is present.

Once the root is located, the CLI gathers artifacts through dedicated collectors:

- `collect_git_commits` – Retrieves history using **libgit2**, with a fallback to the `git` CLI on Windows.
- `collect_readme` – Captures the project's README file.
- `collect_docs` – Walks documentation directories.
- `collect_rust_module_headers` – Extracts Rust module summaries.
- `collect_project_rules` – Imports project-rules files.

Not every commit is kept. The collector filters for **substantive commits** that are at least 120 characters long or use conventional-commit prefixes. This prevents noise from trivial changes like "fix typo" from bloating the initial context.

## Stage 2: Budget-Aware Pruning and Chunking

Because LLM providers enforce input limits, the gathered sources must fit within a token budget. In [`crates/ai-memory-consolidate/src/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/bootstrap.rs), the `prune_sources_to_budget` function (lines 1004–1029) estimates token usage at approximately **4 characters per token** and drops low-priority items until the total falls under `max_input_tokens`.

If the remaining material still exceeds `chunk_input_tokens`, the pipeline invokes `plan_bootstrap_chunks` to split the source list into sequential chunks. This guarantees that every LLM request stays within provider limits while preserving as much historical context as possible.

## Stage 3: Server-Side Processing and Wiki Generation

After local preparation, the CLI POSTs the JSON bundle to `POST /admin/bootstrap`. The server—also implemented in [`crates/ai-memory-consolidate/src/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/bootstrap.rs) via `process_sources` (lines 92–122)—re-runs the same pruning logic for parity, then checks idempotency by looking for an existing [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest. If the manifest exists and the `--force` flag is not supplied, the operation aborts to prevent accidental overwrites.

For each chunk, the server builds a `ChatRequest` using `build_chunk_request` and the system prompt defined in [`crates/ai-memory-consolidate/prompts/bootstrap_system.md`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/prompts/bootstrap_system.md). The LLM returns a `BootstrapBatch` containing `BootstrapPage` descriptors, which are then committed to the wiki via `Wiki::apply_batch`. Finally, the server generates a **bootstrap manifest** ([`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md)) summarizing the import, including source counts, token usage, rationales, and the complete page list.

## CLI Usage Examples

You can run the bootstrap command from any directory. If the current working directory contains a git repository, the CLI auto-detects the root:

```bash

# Import the current repository (auto-detect .git)

ai-memory bootstrap

```

When the current directory is not a git repo, pass an explicit path:

```bash

# Specify a repository path explicitly

ai-memory bootstrap --repo-path /path/to/project

```

To preview what would be sent without invoking the LLM or writing pages, use `--dry-run`:

```bash

# Preview the import without making LLM calls

ai-memory bootstrap --dry-run

```

A dry-run produces output similar to this:

```text
Dry-run complete for my-workspace/my-project

Sources loaded into the LLM:
  - 23 git commit summar...
  - README
  - 5 doc file(s) (under docs/)
  - 2 Rust module header(s)
  -> ~12 500 input tokens estimated (dropped 7 lower-priority source(s) to stay under budget)

(dry-run -- no LLM call, no pages written)

```

To re-run the bootstrap on a project that has already been imported, override the idempotency check:

```bash

# Force a re-run on an already-bootstrapped project

ai-memory bootstrap --force

```

## Key Files in the Bootstrap Pipeline

Understanding the bootstrap workflow requires familiarity with these core files:

- **[`crates/ai-memory-cli/src/commands/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/bootstrap.rs)** – CLI entry point that resolves the repo, collects sources, prunes them, and POSTs the bundle to the server.
- **[`crates/ai-memory-consolidate/src/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/bootstrap.rs)** – Core library containing source collectors (`collect_sources`), budgeting logic (`prune_sources_to_budget`), chunk planning (`plan_bootstrap_chunks`), and server-side `process_sources`.
- **[`crates/ai-memory-consolidate/prompts/bootstrap_system.md`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/prompts/bootstrap_system.md)** – System prompt fed to the LLM that defines the expected output format and security boundaries.
- **[`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs)** – Wiki API used indirectly by `process_sources` to write generated pages and the manifest.
- **[`crates/ai-memory-store/src/reader_pool.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader_pool.rs)** – Reader pool used for the idempotency check before creating a new bootstrap run.

## Summary

- The `ai-memory bootstrap` command imports history through a three-stage pipeline: local collection, token-budget pruning, and server-side LLM processing.
- `collect_sources` in [`crates/ai-memory-consolidate/src/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/bootstrap.rs) gathers git commits, READMEs, docs, and Rust module headers, filtering for substantive commits only.
- `prune_sources_to_budget` estimates tokens at ~4 characters per token and drops low-priority sources to stay under `max_input_tokens`, splitting into chunks when necessary.
- The server-side `process_sources` function checks idempotency via [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md), forces regeneration only with `--force`, and generates wiki pages through `Wiki::apply_batch`.
- The CLI supports `--repo-path`, `--dry-run`, and `--force` flags for flexible, safe operation.

## Frequently Asked Questions

### How does ai-memory bootstrap find the repository root?

The bootstrap command uses `discover_repo_root` or `discover_main_repo_root` inside [`crates/ai-memory-consolidate/src/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/bootstrap.rs) to locate the `.git` directory. If no git repository is detected, it falls back to the current working directory so the command still works in non-git contexts.

### What counts as a substantive commit during bootstrap collection?

The `collect_git_commits` filter keeps commits that are at least 120 characters long or that use conventional-commit prefixes. This heuristic removes trivial commits—such as single-line typo fixes—from the bundle before token budgeting begins.

### Why does the bootstrap command need to prune sources before sending them to the LLM?

LLM providers enforce strict input token limits. The `prune_sources_to_budget` function estimates usage at roughly 4 characters per token and discards lower-priority items until the total fits under `max_input_tokens`. If the content still exceeds `chunk_input_tokens`, it is split into sequential chunks.

### Can I re-run the bootstrap command on a project that was already imported?

Yes, but only with the `--force` flag. The server checks for an existing [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest and aborts the operation unless `--force` is supplied, preventing accidental overwrites of the existing wiki.