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

> Understand the difference between ai-memory bootstrap and ai-memory reindex. Learn when to use bootstrap for initial setup and reindex for rebuilding your search index.

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

---

**`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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/bootstrap.rs)), making it safe to run multiple times—it simply overwrites the manifest without corrupting existing pages.

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs)).

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`.