How the ai-memory Bootstrap Command Imports Existing Project History

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. 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, 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 via process_sources (lines 92–122)—re-runs the same pruning logic for parity, then checks idempotency by looking for an existing 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. 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) 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:

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

ai-memory bootstrap

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

# 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:

# Preview the import without making LLM calls

ai-memory bootstrap --dry-run

A dry-run produces output similar to this:

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:

# 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 – 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 – 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 – System prompt fed to the LLM that defines the expected output format and security boundaries.
• 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 – 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 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, 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 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 manifest and aborts the operation unless --force is supplied, preventing accidental overwrites of the existing wiki.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}