ai-memory Bootstrap vs Reindex: What's the Difference and When to Use Each

ai-memory bootstrap creates initial markdown pages from your project source files and writes a manifest, while ai-memory reindex rebuilds the SQLite search index from existing wiki files without touching the markdown content.

The akitaonrails/ai-memory tool maintains a dual-storage architecture: plain-text markdown pages in a wiki directory and a derived SQLite database that indexes those pages for fast search and link traversal. Understanding when to use bootstrap versus reindex ensures you maintain data integrity and avoid corruption.

Core Architectural Split

ai-memory separates content creation from index generation. The bootstrap command populates the source of truth (markdown files), while reindex materializes the searchable view (SQLite database) from that source. This design lets you manually edit wiki files or recover from database corruption without losing your captured knowledge.

According to the source code in docs/usage.md (lines 252–265), the bootstrap command reads repository sources like git logs, README files, and documentation to generate an initial set of pages. The reindex command, documented in docs/lifecycle-ops.md (lines 22–25), operates strictly on the existing wiki directory to rebuild database tables from scratch.

ai-memory Bootstrap: Seeding the Wiki

Purpose: Generate initial markdown pages that describe your project structure and create a bootstrap manifest (bootstrap.md) tracking what was created.

When to run:

• First-time adoption of ai-memory in an existing repository
• After major structural changes that warrant re-documenting the project
• When you want to preview (--dry-run) what pages would be created

What it does:

1. Reads source files: git log, README.md, docs/ contents, and related project metadata
2. Prunes collected sources before server transmission to reduce noise
3. Writes generated pages to <wiki>/<workspace>/<project>/
4. Creates bootstrap.md manifest listing every page written

Key characteristic: The bootstrap command never touches SQLite tables. It operates purely in the wiki layer (crates/ai-memory-wiki/src/bootstrap.rs), making it safe to run multiple times—it simply overwrites the manifest without corrupting existing pages.

# Preview what would be created

cd /my/project
ai-memory bootstrap --dry-run

# Actually seed the wiki

ai-memory bootstrap

ai-memory Reindex: Rebuilding the Search Index

Purpose: Recreate the SQLite database from existing markdown wiki files when the index is missing, corrupted, or out-of-sync with the content.

When to run:

• After manually editing wiki markdown files
• Following a crash that left the database inconsistent
• When ai-memory status reports database corruption
• After reset --reindex workflows

What it does:

1. Scans the complete wiki directory structure
2. Parses each markdown file and extracts front-matter (tier, pinned, etc.)
3. Builds the page-link graph for relationship traversal
4. Populates FTS5 full-text search tables
5. Rewrites all SQLite tables (pages, links, fts) from scratch

Critical safety constraint: The reindex command refuses to run while the server is active because the database must be empty before re-indexing begins. This prevents silent data loss. The implementation lives in the store layer (crates/ai-memory-store/src/reader.rs).

# Standard reindex workflow (server must be stopped)

ai-memory stop
ai-memory reindex --data-dir $(ai-memory config get data-dir)
ai-memory start

Side-by-Side Comparison

Aspect	ai-memory bootstrap	ai-memory reindex
Primary operation	Create markdown content	Rebuild SQLite index
Reads from	Git history, source files, README	Existing wiki markdown files
Writes to	Wiki directory, bootstrap.md manifest	SQLite database tables only
Deletes existing data	No (overwrites manifest only)	Yes (requires empty DB first)
Server requirement	None	Must be stopped
Idempotence	Safe to re-run	Aborts if DB not empty
Layer	ai-memory-wiki crate	ai-memory-store crate

Recovery Workflow Example

When database corruption occurs, the reindex command provides a clean recovery path without touching your accumulated knowledge:

# Detect corruption

ai-memory status

# Error: Database disk image is malformed

# Recover by rebuilding index from wiki source

ai-memory stop
ai-memory reindex --data-dir /var/lib/ai-memory/wiki
ai-memory start

# Verify restoration

ai-memory status  # Should report healthy

This workflow leverages the architectural separation: your markdown files remain intact as the source of truth, while the derived database can be reconstructed at any time.

Summary

• ai-memory bootstrap seeds the wiki with initial project documentation and creates a manifest—use it when adopting the tool or restructuring a project
• ai-memory reindex rebuilds the SQLite search index from existing wiki files—use it for recovery, after manual edits, or when the database drifts from the content
• Bootstrap operates in the wiki layer without database dependencies; reindex operates in the store layer and requires server shutdown
• The bootstrap manifest (bootstrap.md) and empty-database guard on reindex work together to prevent accidental data loss

Frequently Asked Questions

Can I run bootstrap after I've already captured significant knowledge?

Yes. Running bootstrap on an established wiki is considered a re-bootstrap: it overwrites the bootstrap.md manifest but leaves existing pages untouched. Generated pages may collide with manual edits, so review with --dry-run first.

Why does reindex refuse to run when the server is active?

The ai-memory server maintains open database connections and background indexing tasks. Reindex requires exclusive access to truncate and rebuild tables. Running concurrently would cause locking conflicts and potential corruption. Always stop the server first.

What happens to my manual wiki edits during reindex?

Nothing. The reindex command is read-only with respect to markdown files. It parses your edits, extracts updated front-matter, and incorporates them into the fresh database. Your manual changes are preserved and become searchable.

How do I know which command I need?

If your wiki directory is empty or outdated relative to your project—use bootstrap. If your wiki has good content but search is broken or missing—use reindex. When in doubt, check ai-memory status: database errors indicate reindex; missing pages indicate bootstrap.

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