| name | box-index-rebuild |
| description | Rebuild a folder's _index.json (or the whole workspace's indexes) by walking the local Box Drive filesystem and re-reading every memory's frontmatter. Also resolves Box Drive .conflict files that arise when two clients write the same index, and detects stale companions whose binary changed. FS-only, no Box API. |
| argument-hint | [<relative-folder-path>] [--check] [--companions-only] [--team=<name>] |
/box-index-rebuild
If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.
Scan folders on the local Box Drive mount, re-read memory frontmatter, write fresh _index.json files. The source of truth is always the memory files themselves; the index is derived state. Rebuilding from source is always safe.
Usage
/box-index-rebuild [<relative-folder-path>] [--check] [--companions-only] [--team=<name>]
Examples:
/box-index-rebuild — rebuild every per-folder index in the workspace/box-index-rebuild memories/ — rebuild just one folder/box-index-rebuild --check — diagnostic only; don't write/box-index-rebuild --companions-only — only check companion hash freshness/box-index-rebuild --team=engineering — rebuild one team's subtree
What to do
- Verify workspace + backend. Read
_box-memory.json; confirm backend: local; confirm Box Drive writable.
- Determine target folders. Workspace-wide / folder-scoped / team-scoped per args.
- List local FS of target folder. Capture every file: relative path, size, mtime.
- Parse memory files. For each
*.md (excluding README.md, _*.json, anything starting with _):
- Read file content
- Parse YAML frontmatter (between
--- delimiters)
- Extract:
id, slug, title, kind, status, team, tags, related, companion_for, sha256, created_at, updated_at
- If frontmatter malformed (missing required fields, no
--- delimiters), capture in orphans[] list with the problem. Don't drop.
- Build entry list + inverted maps:
by_id[<mem_id>] → entries array indexby_slug[<slug>] → mem_idby_wikilink[<title>] → mem_idby_kind[<kind>] → [mem_id, ...]by_tag[<tag>] → [mem_id, ...]by_status[<status>] → [mem_id, ...]by_companion_for[<binary_relative_path>] → mem_id (companion entries)
- Detect collisions. Same
id across two files → conflict (should never happen; if it does, surface for user). Same slug across two status: active memories → conflict; flag both.
- Companion staleness check (also runs in
--companions-only mode):
- For each companion entry, locate the binary at
<workspace>/<companion_for.local_path>
- Compute current SHA256 of the binary
- Compare to stored
companion_for.sha256
- Match → companion current
- Differ → mark as
stale: true in the new index; add to stale_companions[] report; suggest /box-companion <relative-path> to regenerate
- Binary missing from local FS → mark as
orphaned: true; add to orphan_companions[]; surface separately (the binary may be in Box cloud but not synced locally yet, OR it was deleted)
- Handle
.conflict files. Box Drive creates files like _index.json.conflict-<timestamp> when two writers wrote the same path:
- If detected, parse both and merge by union of entries + most-recent-
updated_at-wins per entry ID
- After successful merge, delete the
.conflict files
- Surface in the report so the user knows a merge happened
- Stale lockfile detection. If
_box-memory.lock exists and renewed_at is >30s old, force-remove it (it's stuck). Mention in the report.
- Acquire workspace lock, write the new
_index.json atomically, release lock. Skip writes if --check mode.
- Rebuild rollup at workspace root (
_index.json) after all per-folder indexes are fresh.
- Report:
✓ Index rebuild complete (or check complete).
Scope: <workspace | folder | team>
Folders processed: <N>
Memories indexed: <N>
Companions indexed: <N>
Issues found:
Stale companions: <N> (hash mismatch — binary changed since review)
Orphan companions: <N> (binary not in local FS; may not be synced yet)
Frontmatter errors: <N> (parse failures — see below)
ID collisions: <N>
Slug collisions: <N>
.conflict files merged: <N>
Stale lockfile removed: <yes/no>
For each stale companion, give:
- companion: <relative path> (id: <mem_...>)
binary: <binary relative path>
reviewed: <reviewed_at>
stored sha: <hash>
current sha: <hash>
→ /box-companion <relative path> to regenerate
For each frontmatter error:
- file: <relative path>
error: <e.g. "missing 'id' field", "no closing --- delimiter">
→ fix manually, or move to <workspace>/_archive/
Check mode (--check)
Same scan; don't write. Compare what the rebuild WOULD produce against the current _index.json. Report drift:
- Entries in current index that don't exist in source (binary deleted from local FS — may be Box Drive un-syncing OR true delete)
- Entries in source that aren't in current index (added files not yet indexed)
- Entries where frontmatter doesn't match current entry (modified files)
Useful before committing to a rebuild — "what would change?"
Performance
- Each file read is one local FS read. 200 memories → ~200 reads. Fast.
- For 1000+ memory workspaces, batch by folder.
- Rollup rebuild reads only per-folder indexes (much cheaper than full rebuild).
When to suggest rebuild
After other skills detect drift (recall returning stale results, write hitting unexpected slug collisions), suggest:
Note: rebuild detected <N> issues. Resolve before relying on recall for those memories.
Don't
- Don't modify memory files during rebuild. Index is derived; sources are authoritative.
- Don't delete orphan or frontmatter-error files — surface them; let the user decide.
- Don't rebuild silently if non-trivial drift was found. Always report what changed.
- Don't call Box's API or read any URL.
Errors
- Permission denied on a folder → "Skipped folder
<path> — no read access"
- Frontmatter parse failure on a memory → captured in report, doesn't fail the rebuild
- Cannot read a memory file → captured as "unreadable", doesn't fail the rebuild
- Lock cannot be acquired → another writer is active OR a stale lock — force-remove if >30s stale and retry
