Keeping the Index Fresh

Keeping the Index Fresh

The index is the chart — it records where things are (metadata + git anchors) and the embedding vectors that power semantic search. Keeping it current is cheap and incremental: reindex re-embeds only what changed. Remember: even a lagging index never produces a stale answer, because snippets are reconstructed live (see Never Stale: Live Reconstruction). A lagging index only affects whether brand-new symbols are discoverable yet.

Index modes

Command	Mode	What it does
columbus reindex	incremental (default)	Update only what changed since last index
columbus reindex --changed	fast path	Only files dirty in the working tree
columbus reindex --full	full	Reindex everything from scratch (memories preserved)
columbus reindex --clean	clean	Drop all index data (config + memories preserved)
columbus reindex --status	status	Report state without writing

Typical incremental run

$ columbus reindex
Indexed 4 file(s) [incremental mode]
  unchanged: 0  deleted: 0  symbols: 7
  index now: 4 files

Check state without writing

$ columbus reindex --status
Would index 0 file(s) [status mode]
  unchanged: 4  deleted: 0  symbols: 0
  index now: 4 files

Great for agents: read freshness, decide whether a write is needed.

When to use which

• After edits, during a session: columbus reindex --changed (fastest).
• Routine refresh: columbus reindex (incremental).
• Schema/grammar upgrade, or something looks off: columbus reindex --full.
• Start over (keep config + memories): columbus reindex --clean then columbus reindex.

Freshness signals

columbus graphs reports freshness in text, and the --json projection exposes a structured block agents can act on:

"freshness":{"indexed_head":"c3035af…","dirty":false,"last_indexed_at":"2026-06-07T12:31:18Z","stale":false}

• indexed_head — the git commit the index was built against
• dirty — working tree has uncommitted changes
• stale — the index is behind the working tree

What's indexed

Files are discovered from the working tree, honoring the exclude globs and max_file_size in .columbus.json (see Configuration). Supported languages are listed in Supported Languages.

Related

Command: reindex · Configuration