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

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

ai-memory bootstrap --dry-run

Perform a standard bootstrap against a local server:

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

Force re-import to overwrite existing history:

ai-memory bootstrap --force

Complete CI-style migration workflow:

# 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 – Documents the CLI workflow, required LLM configuration, and manifest handling semantics
• crates/ai-memory-mcp/src/admin.rs – Contains the handle_bootstrap implementation managing POST /admin/bootstrap requests and LLM integration
• docs/design-decisions.md – Explains the rationale for bootstrap.md manifests and re-bootstrap semantics
• 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 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 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 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 that serializes concurrent requests. While the lock prevents race conditions, concurrent bootstraps of the same project are unnecessary due to the idempotent manifest system.

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