docs: recommend Git LFS for team-shared graph artifact

[angusgastle]

Summary

Adds guidance to the Team-Shared Graph Artifact section recommending Git LFS for the .codebase-memory/graph.db.zst artifact in team-shared repos.

The problem we hit

The existing guidance told teams to commit graph.db.zst as a regular file with merge=ours. That works for merge conflicts but ignores the bigger issue: the artifact is a ~20MB binary that regenerates on every re-index, and committing it plainly stores a full new blob each time.

We discovered this on a real monorepo (internal HR/finance app, ~2047 files). Within a normal week of indexing:

• The graph.db.zst blob was committed hundreds of times across history.
• The repo ballooned to ~7GB of bloat from that single file.
• Fresh clones were downloading gigabytes of binary blobs that were functionally identical snapshots.
• main alone carried 352 commits with the raw ~20MB blob (~6 GB).

We reclaimed the space with a git-filter-repo history rewrite that converted the artifact to a Git LFS pointer across all history. After the rewrite, a fresh clone dropped from ~6 GB to ~534 MB — roughly a 10× reduction — and main's .git went from 5.9 GB to under 1 GB.

The fix

The artifact still regenerates, but with LFS the binary is stored out-of-band rather than as a new blob per commit. The .gitattributes tracking line:

.codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text

The merge=ours conflict-avoidance the original guidance emphasized is preserved by LFS's own merge=lfs handler.

What this PR changes

• Adds a "Use Git LFS for team repos" bullet to the Team-Shared Graph Artifact section.
• Notes that migrating an existing repo where the artifact was already committed plainly requires stripping historical blobs with git-filter-repo first (the merge=ours → LFS switch on its own only affects future commits).

Notes

• This is a docs-only change; no code paths are touched.
• The export path still auto-creates the merge=ours line on first export. A follow-up could auto-emit the LFS line (or detect an existing LFS setup), but that's a code change left for a separate PR.
• The ~7GB figure comes from our internal history-rewrite log; the ratio (10× clone reduction after LFS) is what generalizes.

🤖 Generated with Claude Code

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.