kb-index

KB Index — Smart Index Update

Update indexes efficiently. By default, detects what changed and updates only affected entries. Full rebuild available when needed.

Configuration and exclusions

If .para-kb/config.json exists, use its para_roots, index_file_names, and exclusions instead of assuming numbered folder names. Never treat .para-kb/, the Obsidian config directory, the active telemetry JSONL, telemetry archives, runtime state, or generated reports as knowledge documents or index entries.

Usage

/kb-index                      # Smart update (diff-based, fast)
/kb-index --full               # Full rebuild (scan everything)
/kb-index --category Projects  # Update one category only
/kb-index --dry-run            # Preview changes without writing

Update Strategy

Choose the lightest approach that fits the situation:

Tier 1: Per-File Update (via kb-ingest) — ~200 tokens

When: A single file was ingested or moved. How: kb-ingest already handles this — adds one line to _index.md, updates counts. No need to run kb-index separately.

Tier 2: Smart Diff Update (default kb-index) — ~500-1500 tokens

When: A few files changed, or "something feels off." How: Compare existing _index.md entries against actual files on disk. Only process differences.

Tier 3: Full Rebuild (kb-index --full) — ~3-4K tokens

When: Major reorganization, initial setup, or indexes are badly corrupted. How: Scan everything from scratch, regenerate all indexes.

Tier 2: Smart Diff — Execution Flow

This is the default behavior when you run /kb-index.

Step 1: READ existing indexes (cheap — ~200 tokens total)
  Read top-level index.md (~30 lines)
  Read PARA category _index.md files
  If a changed file is inside a project folder and that folder has _index.md, read that project hub too
  Extract: listed items, counts, last updated date

Step 2: DETECT changes (cheap — tool calls only, no file reads)
  For each PARA category:
    Glob: list current subdirectories and .md files on disk
    Compare against items listed in _index.md
    Classify each item:
      MATCH    — in index AND on disk → skip (no action)
      ADDED    — on disk but NOT in index → needs adding
      REMOVED  — in index but NOT on disk → needs removing

  If zero differences found:
    Log "[date] index | no changes detected" → done
    Total cost: ~200 tokens (just reading indexes + globs)

Step 3: PROCESS only differences
  For ADDED items only:
    Read the new file's overview/frontmatter (~50-100 tokens per file)
    Generate one-line index entry

  For REMOVED items:
    Delete the line from _index.md

  Skip MATCH items entirely — don't re-read, don't regenerate

Step 4: UPDATE indexes
  Edit (not rewrite) each affected _index.md:
    Insert new entries, remove deleted entries
    Update summary count line
    Update "updated: {today}" in frontmatter

  Update top-level index.md:
    Adjust category counts
    Update Recent Activity from log.md (last 5 entries)

  If a changed file is inside a project folder that has _index.md:
    Update the project hub, especially its local document list and updated date

Step 5: LOG
  "[date] index-update | added N, removed M | touched K categories"