How to Migrate Existing Projects Using ai-memory Bootstrap

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. 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, all files under docs/, and any other markdown files not already present in the wiki. This collection phase is detailed in docs/usage.md and captures the full narrative of your project history.

Step 3: Manifest Generation

In crates/ai-memory-wiki/src/wiki.rs at line 1328, the tool generates a 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, 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 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:

ai-memory bootstrap --dry-run

To perform the actual migration and create the wiki structure:

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:

ai-memory bootstrap --force

To verify the import succeeded:

ai-memory search "initialize project"

Complete workflow for an existing repository:

# 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: Core bootstrap logic handling manifest creation at line 1328 and page generation at line 1829.
• crates/ai-memory-store/src/lib.rs: FTS5 indexing implementation at line 2353 that makes bootstrap pages searchable.
• docs/usage.md: User-level documentation describing bootstrap flags and options.
• docs/install.md: Mid-project installation guidance and repository detection logic.
• 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 manifest with unique tokens to prevent duplicate imports, implemented in wiki.rs.
• Source code in wiki.rs (lines 1328, 1829) handles page generation while 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, 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 that ensures idempotency. As implemented at line 1328 of 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 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.

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