# Understanding the ai-memory Bootstrap Command Flow for Importing Existing Project History

> Learn the ai-memory bootstrap command flow for importing project history. Discover how it prioritizes sources, summarizes with LLMs, and creates a manifest for efficient data integration.

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

---

**The `ai-memory bootstrap` command imports existing project history by collecting prioritized sources, sending them to an LLM for summarization via the POST `/admin/bootstrap` endpoint, and creating a [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest to ensure idempotent operations.**

The `ai-memory bootstrap` command serves as the primary entry point for seeding a fresh ai-memory wiki with historical content from an existing codebase. According to the akitaonrails/ai-memory source code, this workflow transforms raw repository data into searchable markdown documentation through a three-phase pipeline. Understanding the bootstrap command flow for importing existing project history is essential for teams migrating legacy codebases into the ai-memory knowledge base.

## Bootstrap Command Architecture Overview

The bootstrap workflow orchestrates source collection, LLM-based content generation, and manifest management to populate the wiki without manual copying. The command is implemented in the CLI layer and interacts with the ai-memory server through dedicated admin endpoints. Users can control the process through flags like `--dry-run` for previews and `--force` to overwrite existing manifests.

## Phase 1: Source Collection and Prioritization

The bootstrap collector walks the repository filesystem and version control history to gather contextually significant documents.

### Prioritized Source Types

The `process_sources` routine extracts content from multiple authoritative locations:

- **Git history**: Complete output of `git log` for commit context
- **Project documentation**: The top-level README and all files under `docs/`
- **Rule files**: Project configuration files including [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) and contents of `_rules/` directories
- **Rust documentation**: Module documentation extracted from source code comments

### Dry-Run Validation

Before committing changes, developers can preview the import scope using the `--dry-run` flag. This mode executes the collection phase without persisting data to the wiki, displaying exactly which files would be processed during a live bootstrap.

## Phase 2: LLM Summarization and Import

Once sources are collected, the system converts raw text into structured wiki pages through AI processing.

### The Admin Bootstrap Endpoint

For each selected source, the CLI sends the raw text to the running ai-memory server via a **POST `/admin/bootstrap`** request. The server handler, implemented in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs), coordinates the transformation pipeline.

### LLM Provider Requirements

The bootstrap operation requires a configured LLM provider (such as OpenAI or Claude) to generate markdown content. According to the `handle_bootstrap` implementation in [`admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/admin.rs), requests fail with **HTTP 503 Service Unavailable** if no provider is configured. The server writes generated pages directly into the wiki while explicitly excluding the special [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest from indexing.

## Phase 3: Manifest Creation and Idempotency Guarantees

To prevent duplicate imports and enable incremental updates, the bootstrap process implements sophisticated locking and manifest systems.

### The bootstrap.md Manifest

After successful completion, the system creates a per-project manifest at `<wiki>/<workspace>/<project>/bootstrap.md`. This file catalogs every imported source and serves as a guard against redundant operations. Subsequent bootstrap attempts skip processing if the manifest exists unless the user specifies the `--force` flag to trigger a re-bootstrap.

### Concurrency Control

The server maintains a global `bootstrap_lock` using a `tokio::sync::Mutex` to serialize concurrent bootstrap requests. This mechanism prevents race conditions when multiple clients attempt to import history simultaneously, ensuring data integrity within the wiki storage layer.

## Practical Bootstrap Commands

Execute the bootstrap workflow using the ai-memory CLI with environment-specific configurations.

Preview the import without writing data:

```bash
ai-memory bootstrap --dry-run

```

Perform a standard bootstrap against a local server:

```bash
export AI_MEMORY_SERVER_URL="http://localhost:49374"
ai-memory bootstrap

```

Force re-import to overwrite existing history:

```bash
ai-memory bootstrap --force

```

Complete CI-style migration workflow:

```bash

# 1. Start server with LLM provider

ai-memory serve --transport http --bind 127.0.0.1:49374 \
    --llm-provider openai-oauth

# 2. Verify connectivity

ai-memory status

# 3. Import project history

ai-memory bootstrap

# 4. Query imported knowledge

ai-memory search "initial project design"

```

## Key Implementation Files

The bootstrap functionality spans multiple components within the akitaonrails/ai-memory repository:

- [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) – Documents the CLI workflow, required LLM configuration, and manifest handling semantics
- [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) – Contains the `handle_bootstrap` implementation managing POST `/admin/bootstrap` requests and LLM integration
- [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) – Explains the rationale for bootstrap.md manifests and re-bootstrap semantics
- [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) – Details how bootstrap-related marker files interact with the wiki watcher system

## Summary

- The bootstrap command flow for importing existing project history consists of three phases: source collection, LLM summarization via POST `/admin/bootstrap`, and manifest creation.
- **Source Collection** gathers `git log` output, README files, `docs/` contents, rule files, and Rust documentation through the `process_sources` routine.
- **LLM Processing** requires a configured provider and returns HTTP 503 if unavailable, generating markdown pages stored directly in the wiki.
- **Idempotency** is enforced through the [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest and a global `bootstrap_lock` mutex preventing concurrent modifications.
- The `--dry-run` flag enables safe previewing, while `--force` allows intentional re-bootstrapping of project history.

## Frequently Asked Questions

### What happens if I run bootstrap without an LLM provider configured?

The server returns an HTTP 503 error because the `handle_bootstrap` function in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) cannot generate markdown summaries without LLM access. You must configure a provider like OpenAI or Claude using the `--llm-provider` flag when starting the server.

### Can I preview which files will be imported before running bootstrap?

Yes. Use the `--dry-run` flag with the bootstrap command to execute the collection phase without persisting data. This displays the prioritized list of sources including git history and documentation files that would be processed during a live import.

### How does ai-memory prevent duplicate imports when bootstrapping the same project twice?

The system creates a [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest file at `<wiki>/<workspace>/<project>/bootstrap.md` after the first successful bootstrap. Subsequent attempts detect this file and skip processing unless you specify the `--force` flag, which triggers a complete re-bootstrap and manifest overwrite.

### Is the bootstrap process safe to run concurrently from multiple terminals?

The implementation includes a global `bootstrap_lock` using `tokio::sync::Mutex` in [`admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/admin.rs) that serializes concurrent requests. While the lock prevents race conditions, concurrent bootstraps of the same project are unnecessary due to the idempotent manifest system.