Skip to content

feat: add greplica graph gc to prune stale knowledge-graph memory - #108

Open
burrows99 wants to merge 2 commits into
Autoloops:mainfrom
burrows99:feat/graph-gc
Open

feat: add greplica graph gc to prune stale knowledge-graph memory#108
burrows99 wants to merge 2 commits into
Autoloops:mainfrom
burrows99:feat/graph-gc

Conversation

@burrows99

@burrows99 burrows99 commented Jul 6, 2026

Copy link
Copy Markdown

Closes #24.

greplica graph gc [--dry-run] prunes memory a repo no longer supports.

What it detects

  • Stale anchors — components/claims whose code_anchor file no longer exists on disk. Reuses the existing code-anchor audit (auditClaimCodeAnchors, already behind graph audit anchors) for claims, and adds the same file check for component anchors.
  • Orphaned claims/flows — no edge references them.
  • Dangling edges — an endpoint object row no longer exists.

Prune semantics

  • Pruning a subject cascades to every edge that touches it (a stale claim's about/evidenced_by edges go with it), all in a single transaction.
  • Object rows are global across repos (bug: Graph object IDs are global across repos, causing cross-repo memory collisions #103), so gc is scope-safe: it only unlinks this repo's graph_memberships + repo-scoped graph_object_embeddings, and deletes the shared object row only when no membership anywhere still references it. No cross-repo damage.
  • Superseded objects are left alone (supersession is history).
  • --dry-run reports the plan and touches nothing.

Design note (the open question from the thread)

The issue says "permanently prunes," and #103 makes a naive global DELETE dangerous. This PR reconciles both: hard-delete, but gated on no remaining references, so it reclaims rows without affecting other repos. Happy to switch to a pure retire-via-supersession model if maintainers prefer.

Tests

scripts/check-graph-gc.js (wired into npm test) seeds a temp DB with one of each defect class plus healthy objects, then asserts: dry-run counts + zero mutation, real run prunes exactly the defects with cascaded edges/memberships/embeddings, healthy objects untouched, and a second pass is a no-op. npm test and npm run typecheck both pass.

Demo

Recording being attached in a comment.

Adds a `graph gc [--dry-run]` command that removes memory a repo no longer
supports:

- stale anchors — components/claims whose `code_anchor` file was deleted
  (reuses the existing code-anchor audit for claims; adds the same check for
  component anchors)
- orphaned claims/flows — no edge references them
- dangling edges — an endpoint object no longer exists

Pruning a subject cascades to every edge that touches it and runs in a single
transaction. Object rows are global across repos (Autoloops#103), so gc only unlinks
this repo's `graph_memberships` + repo-scoped `graph_object_embeddings` and
deletes the shared row only when no membership anywhere still references it.

`--dry-run` reports the plan without touching the database. Adds
`scripts/check-graph-gc.js` (wired into `npm test`) covering all three defect
classes, cascade cleanup, healthy-object safety, and idempotency.

Closes Autoloops#24

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@burrows99

burrows99 commented Jul 6, 2026

Copy link
Copy Markdown
Author

Full graph gc walkthrough covering every behavior #24 asks for. One graph is seeded with all the rot at once: a stale code anchor (we delete src/cache.ts), an orphaned claim and an orphaned flow (no edges), and a dangling edge (points at a deleted subject). graph gc --dry-run reports all of it without touching the database; graph gc then prunes it (cascading edges, memberships, embeddings) and leaves only the healthy claim.

gc-full.mp4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Add graph cleanup and pruning command

1 participant