Feature: Add graph cleanup and pruning command

[Pallavikumarimdb]

Problem

As repositories evolve, files are deleted, renamed, or refactored. Over several coding sessions:

1. Components might point to code anchors (code_anchor) that no longer exist on disk.
2. Claims, flows, or sources can become completely orphaned (disconnected from any active component or flow).
3. Edges might point to deleted/non-existent subject IDs.

Currently, Greplica has no way to audit the health of the local knowledge graph or prune these stale, dangling, or orphaned entities. Stale data remains in the database and is retrieved during search, which wastes context window tokens and degrades the coding agent's performance.

Proposed Solution

Introduce a new CLI command - greplica graph gc - to safely clean up the repository's local memory database. It should support a --dry-run flag to preview changes before applying them.

Expected Behavior

• Stale Code Anchors: Check if code_anchor files exist on disk. If a file is missing, flag/prune the component.
• Orphaned Claims/Flows: Find claims or flows with no incoming or outgoing edges, or claims whose related components/flows have been deleted.
• Dangling Edges: Identify and prune edges where either the from_id or to_id refers to an entity that no longer exists in the graph.
• Cascading Deletes: When pruning an entity, ensure its corresponding database memberships (in the graph_memberships table) and associated embeddings are cleanly deleted to avoid database constraints violations.
• CLI Command routing:
  • greplica graph gc --dry-run: Runs the audit scan and prints the report of stale/orphaned items without modifying the database.
  • greplica graph gc: Permanently prunes the database and outputs a summary of deleted components, claims, flows, and edges.

[chiragbiradar]

Hi @kushalpatil07, I'd like to take this up if it's available.

My plan:

• Add a greplica graph gc command with a --dry-run flag that audits the graph and prints a report without modifying the database
• Reuse the existing code-anchor audit (libs/knowledge-graph/code-anchors/audit.ts) to detect components pointing to files that no longer exist on disk
• Detect orphaned claims/flows (no incoming or outgoing edges) and dangling edges (from_id/to_id referencing deleted entities)
• On a real run, prune entities with cascading cleanup of graph_memberships rows and associated embeddings, then print a summary of what was deleted
• Add a scripts/check-graph-gc.js smoke test following the existing check-*.js pattern and wire it into npm test

Happy to adjust the approach if you have a preferred design.

[chiragbiradar]

Following up on my earlier comment with a fuller design before writing code. This also ties into the roadmap discussion on memory freshness: the way I see it, staleness detectors (content hashing / anchor drift, #90 #91) decide what might be bad, and graph gc is the deterministic, human-approved surface that actually removes things. Keeping detection and removal separate keeps gc safe.

Command surface

greplica graph gc --dry-run    # audit only: prints report of prunable objects, DB untouched
greplica graph gc              # prunes, prints summary of deletions
greplica graph gc --json       # machine-readable report (feeds a future audit UI)

Registers next to the existing graph audit anchors command in apps/cli/main.ts — no new top-level command.

Detection passes (in order)

1. Stale code anchors — reuse libs/knowledge-graph/code-anchors/audit.ts (already behind graph audit anchors): anchor file missing on disk flags the component/claim. gc consumes the existing audit result instead of re-implementing it.
2. Dangling edges — edges whose from_id or to_id doesn't resolve to an existing object. New proposals can't create these since fix: report validation error instead of crashing on malformed proposal edges #93, but older databases may still contain them.
3. Orphaned claims/flows — claims left with zero about/evidenced_by edges after pass 2, and flows whose touched components are all gone. Orphans are recomputed after edge removal so one pass doesn't mask the next.
4. Superseded objects — losers of supersedes edges. Default: kept (supersession is history); pruned only with --include-superseded.

Prune semantics

• Single transaction per run — partial prune is worse than no prune.
• Cascade per object: edges → graph_memberships rows → embeddings, mirroring the proposal-apply cleanup path so no constraint violations.
• Summary groups deletions by type with a reason each (stale anchor / dangling / orphan).
• gc only ever touches the current repo's resolved scope. Given bug: Graph object IDs are global across repos, causing cross-repo memory collisions #103 (object IDs are global across repos), scope filtering is the only thing standing between gc and cross-repo damage — I'll be conservative here and add an explicit test that other scopes are untouched.

Dry-run report shape

graph gc report (dry run)
  stale anchors: 3 components, 5 claims
    component.upload_api  anchor app/api/upload-image/route.ts missing
    ...
  dangling edges: 2
  orphaned claims: 4
  superseded (kept, use --include-superseded): 1
run `greplica graph gc` to prune 14 objects

Tests

scripts/check-graph-gc.js in the existing check-*.js style, wired into npm test: seed a temp DB with one of each defect class plus healthy objects, assert dry-run counts, assert gc deletes exactly the defects with cascaded memberships/embeddings, assert healthy objects and foreign scopes untouched.

Open questions

1. Orphaned sources (session sources with no remaining evidenced_by edges) — prune, or keep as provenance history?
2. Is keep-by-default right for superseded objects, or should they prune by default?
3. Worth shaping the --json report for the "human UX for auditing memory" direction on the roadmap? Happy to align output with whatever the web UI needs.

If this looks right I'll start on it.

[burrows99]

Hi @kushalpatil07 @an1ojha, I'd like to take this one, please assign me.

A ~30s demo of the exact problem graph gc solves. I seed memory for a repo, then a refactor deletes a source file (src/cache.ts). graph audit anchors flags the now-stale claim — but nothing prunes it, so the dead claim still shows up in graph read and pollutes every query. graph gc --dry-run shows there's no such command yet. That gap is this issue.

gc-demo.mp4

One design call before I build it: the storage layer is append-only — no DELETE FROM anywhere in libs/storage, and stale objects drop out via supersession (activeSubjectKeys). Should gc hard-delete rows (cascading to graph_memberships + graph_object_embeddings), or retire them via supersession to keep history? I'll follow the issue's --dry-run → prune shape either way.

---

Update — implemented in #108. Full demo of the working command (memory → refactor → graph audit anchors detects the stale claim → graph gc --dry-run plan → graph gc prunes → clean) is attached on the PR. I went with hard-delete gated on "no membership anywhere still references the row," which is safe under #103 (object IDs are global across repos); happy to switch to retire-via-supersession if you'd prefer.

[chiragbiradar]

Nice demo @burrows99 — and good catch on the storage layer being append-only; my design above assumed a cascading delete path that doesn't actually exist (libs/storage has no deletes, retirement happens through supersession in activeSubjectKeys).

On the hard-delete vs retire question, my two cents:

Retire-via-supersession as the default fits the existing invariants better:

• It reuses the mechanism the storage layer is already built around — gc becomes "write retirement records" instead of introducing the first destructive path into an append-only store.
• It's reversible. gc bugs (or an over-aggressive staleness signal from the anchor audit) don't permanently destroy memory a user spent sessions building.
• It preserves provenance: a claim that was pruned because its anchor vanished is itself useful history ("this area of the graph rots fast").

But retire-only has a real cost: graph_object_embeddings and membership rows keep growing, and embeddings are the expensive part. So I'd split the concern:

1. graph gc — retires (supersession), safe, default.
2. graph gc --compact (or a separate command) — hard-deletes rows that have been retired for more than N memory commits, cascading memberships + embeddings. Destructive, opt-in, and by that point the retirement has been visible in dry-run reports long enough for a human to object.

That also answers the open question I had above about orphaned session sources: retire them with everything else, only compact drops them.

Whichever way kushal wants to go — happy if this lands through #108, the problem getting solved matters more than who ships it.