Indexing and Reindexing

Indexing and Reindexing

Atlas answers are only as current as the selected index. This guide explains normal updates, forced rebuilds, exclusions, and freshness checks.

Initial Index

From a repository root:

atlas index .

To use an explicit database:

atlas --db "sqlite://$PWD/.atlas/atlas.db" index .

Incremental Update

Run the same command after source changes:

atlas index .

Atlas may report a delta update when files changed or a no-op when the stored snapshot already matches the workspace.

Forced Reindex

atlas index . --reindex

Use a full rebuild when:

• an upgrade reports an incompatible or stale index format
• parser or language support changed and old files must be reparsed
• atlas doctor recommends a rebuild
• the workspace identity or indexed root was incorrect
• focused troubleshooting confirms the current index is incomplete

Do not make forced reindexing the default workflow. It is slower and discards the benefit of incremental updates.

Watch Mode

Keep a foreground index current:

atlas watch .

Supervised MCP can also maintain freshness:

atlas mcp --supervise

Disable automatic watching when another process owns indexing:

atlas mcp --supervise --watch=false

Semantic Retrieval

Semantic vectors are optional:

atlas index . --enable-vectors

If vectors are disabled or unavailable, Atlas can continue with lexical and graph-backed retrieval. Confirm the active mode with atlas status or atlas doctor.

Excluding Files

Atlas respects .gitignore by default. Add Atlas-specific patterns to:

.atlasignore

Avoid indexing generated outputs, dependency caches, benchmark working copies, or nested repository snapshots unless they are intentionally part of the review surface.

Verify Freshness

atlas status
atlas stats
atlas doctor

When multiple repositories or databases exist, pin both:

atlas --db "sqlite:///absolute/path/.atlas/atlas.db" \
  --repo /absolute/path status

If a running Atlas server is configured, CLI queries may use that server. Unset ATLAS_SERVER_URL or pin an explicit database while diagnosing which index is answering.

Safe Recovery Order

1. Stop active serve, watch, and supervised MCP processes.
2. Run atlas status and atlas doctor.
3. Confirm the repository and database paths.
4. Run atlas migrate when a schema upgrade is required.
5. Rebuild lexical data only when recommended.
6. Run atlas index . --reindex as the final non-destructive repair.
7. Delete .atlas only when a complete data reset is intended.

See Troubleshooting before removing data.

Performance envelope

• Memory (v0.1.42+). Full indexes of repos over ~15,000 candidate files stream in bounded batches — the Linux kernel indexes at ~1.3 GiB peak RSS. Force with ATLAS_STREAM_INDEX=1; tune with ATLAS_STREAM_INDEX_THRESHOLD / ATLAS_STREAM_INDEX_BATCH. ATLAS_GOGC / ATLAS_MEMORY_LIMIT bound the Go runtime on CI.
• CPU (v0.1.43+). The parse/hash pool defaults to all cores. Cap it with atlas index --workers N or ATLAS_INDEX_WORKERS when a large index (e.g. Chromium) would otherwise saturate the machine; 1 pins it to one core.
• Deletions take the whole-module type-check fallback on Go repos (reverse-dependency edges must be re-derived), so a delete delta costs more than an add/modify. Batch deletions when you can.