# How to Migrate Existing Projects Using ai-memory Bootstrap

> Migrate existing projects with ai-memory bootstrap. Scan your codebase, extract context from git history and docs, and build a searchable wiki without altering original files. Run ai-memory bootstrap now.

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

---

**Run `ai-memory bootstrap` in your Git repository root to scan the codebase, extract context from git history and documentation, and generate a searchable wiki without modifying your original files.**

The `ai-memory` tool from the akitaonrails/ai-memory repository enables you to migrate existing projects into a managed, LLM-accessible knowledge base. By using the **bootstrap** sub-command, you can import your commit history, README, and documentation into an internal wiki that preserves every detail of your project's evolution. This guide explains how to safely integrate ai-memory into established codebases while maintaining full version control integrity.

## How the ai-memory Bootstrap Process Works

The bootstrap command executes a six-step pipeline to ingest your existing project without data loss.

### Step 1: Repository Detection

The command locates your repository root by walking upward until it finds a `.git` directory via **libgit2**, as documented in [`docs/install.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md). This ensures the tool operates from the correct project context regardless of your current working directory.

### Step 2: Context Collection

The system reads the **git log**, the top-level [`README.md`](https://github.com/akitaonrails/ai-memory/blob/main/README.md), all files under `docs/`, and any other markdown files not already present in the wiki. This collection phase is detailed in [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) and captures the full narrative of your project history.

### Step 3: Manifest Generation

In [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) at line 1328, the tool generates a [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest file under `<wiki>/<workspace>/<project>/bootstrap.md`. This manifest lists every page to be created and includes a unique **boot token** to guarantee idempotency across multiple runs.

### Step 4: Wiki Page Creation

At line 1829 of [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), the system creates corresponding wiki pages for each source file (e.g., `README.md → README.md` inside the wiki). The content remains unaltered—no LLM processing occurs during this initial import, ensuring a faithful copy of your documentation.

### Step 5: Search Indexing

The new pages are immediately added to the **FTS5** index via [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) at line 2353. This makes the imported content instantly searchable through the `ai-memory search` command.

### Step 6: Idempotent Re-bootstrap

Running `bootstrap` again will not duplicate pages thanks to the boot token tracking. Use `--force` to overwrite existing manifests after major refactors, or `--dry-run` to preview changes without writing to the filesystem.

## Safety Guarantees During Migration

The bootstrap command enforces three critical safety mechanisms to protect your existing codebase:

- **Read-only host access**: The command only reads from your project files and never writes to the original codebase. All output is directed to the `.ai-memory` directory.
- **Deterministic boot tokens**: The `boottoken` stored in the manifest prevents accidental recreation of existing wiki pages.
- **No LLM hallucination**: The initial import is a byte-for-byte faithful copy of source files. LLM-generated content only appears during later consolidation or auto-improve steps, not during bootstrap.

## Post-Bootstrap Workflow and Version Control

After you migrate existing projects using ai-memory bootstrap, the first `ai-memory run <agent>` command automatically detects the newly created wiki and resumes with full historical context. You should commit the `.ai-memory` directory to version control so collaborators share the same knowledge base. If you rewrite git history or perform massive refactors, use `--force` to re-bootstrap cleanly.

## Bootstrap Command Examples

To preview what would be imported without making changes:

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

```

To perform the actual migration and create the wiki structure:

```bash
ai-memory bootstrap

```

This creates `.ai-memory/wiki/<workspace>/<project>/bootstrap.md` and imports your documentation into the searchable index.

To force a re-import after major architectural changes:

```bash
ai-memory bootstrap --force

```

To verify the import succeeded:

```bash
ai-memory search "initialize project"

```

Complete workflow for an existing repository:

```bash

# Ensure clean state before importing

git status

# Bootstrap the wiki with full history

ai-memory bootstrap

# Version control the knowledge base

git add .ai-memory/
git commit -m "Add ai-memory bootstrap"

# Start managed workstream with full context

ai-memory run claude

```

## Key Source Files and Implementation

Understanding the implementation helps troubleshoot migration issues:

- [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs): Core bootstrap logic handling manifest creation at line 1328 and page generation at line 1829.
- [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs): FTS5 indexing implementation at line 2353 that makes bootstrap pages searchable.
- [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md): User-level documentation describing bootstrap flags and options.
- [`docs/install.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md): Mid-project installation guidance and repository detection logic.
- [`docs/wiki-migrations.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/wiki-migrations.md): High-level migration strategy for complex project transitions.

## Summary

- The **bootstrap** sub-command imports existing git history and documentation into a searchable wiki without modifying source files.
- The process creates a [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) manifest with unique tokens to prevent duplicate imports, implemented in [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs).
- Source code in [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs) (lines 1328, 1829) handles page generation while [`store.rs`](https://github.com/akitaonrails/ai-memory/blob/main/store.rs) (line 2353) manages FTS5 indexing.
- Original project files remain read-only during migration; all writes occur within the `.ai-memory` directory.
- Commit the `.ai-memory` directory to version control to share the knowledge base with your team.
- Use `--dry-run` to preview imports and `--force` to re-bootstrap after major repository changes.

## Frequently Asked Questions

### Will ai-memory bootstrap modify my existing source files?

No. According to the implementation in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), the bootstrap command operates in read-only mode regarding your original project files. It only writes to the `.ai-memory` directory, leaving your codebase untouched while creating the internal wiki.

### How do I prevent duplicate wiki pages when running bootstrap multiple times?

The bootstrap process generates a unique **boot token** stored in [`bootstrap.md`](https://github.com/akitaonrails/ai-memory/blob/main/bootstrap.md) that ensures idempotency. As implemented at line 1328 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs), subsequent runs detect existing tokens and skip previously imported files unless you explicitly use the `--force` flag to overwrite.

### Can I see what would be imported before actually running the command?

Yes. Use the `--dry-run` flag to preview the manifest and page list without writing any files to the filesystem. This functionality is documented in [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) and allows you to verify the scope of migration before committing changes to your repository.

### Should I commit the `.ai-memory` directory to version control?

Yes. The directory contains the wiki, configuration, and bootstrap manifest that enable consistent LLM context across team members. Committing it ensures collaborators share the same searchable knowledge base and project history, maintaining state across development environments.