Feat: Add command to promote working memory to main scope (greplica graph promote)

[Pallavikumarimdb]

Problem

Currently, Greplica separates memory into a main scope (committed repo facts) and a working scope (local session edits). When coding agents run the greplica-update-working-memory skill, new claims, flows, and components are written to the working scope.

However, there is no command to promote or "commit" these working claims into the main scope of the branch. The working memory continues to grow indefinitely relative to the main scope, making it hard to maintain a clean boundary between stable codebase facts and active branch-specific modifications.

Proposed Solution

Introduce a new CLI command—greplica graph promote (or greplica graph commit)—that promotes the current working scope changes into the target branch's main scope.

Expected Behavior

1. Command:

   greplica graph promote [--scope <scope_id>]

2. Action:
   • It takes all components, flows, claims, and edges created under the working scope.
   • Re-assigns their memberships to the parent main scope (or the target branch's scope).
   • Cleans up the working scope (making it empty and ready for the next session).
3. Prerequisites for Branch-Awareness (Branch-aware memory: claims may not hold across git branches #20):
   • Having this promotion command is a critical building block for multi-branch merging. Once working memory is promoted to its branch scope, git branch merging can be handled cleanly at the branch-scope level rather than mixing with active uncommitted session memory.

Example Workflow

1. Work session: Agent makes edits, adds 3 new claims to working.
2. Verification: Tests pass, feature is complete.
3. Commit Memory: Developer or agent runs greplica graph promote.
4. Result: The 3 claims are now permanent parts of the main graph scope. working is cleared.

[thvvamshi]

Hi @Pallavikumarimdb and @kushalpatil07! I'd like to take this up if no one else is working on it.

From what I understand, the goal is to add a greplica graph promote command that promotes everything in the working scope to the main scope while preserving the existing graph relationships, and then clears the working scope so it's ready for the next session.

I'll first spend some time understanding how scopes and graph memberships are currently implemented before making any changes. I'll also add tests and update the documentation as part of the PR.

If there's anything specific you'd like me to keep in mind or if you have a preferred approach, I'd be happy to discuss it before getting started. Thanks!

[burrows99]

I'd like to take this one. @kushalpatil07 @an1ojha could you assign it to me?

I read through the scope model first so the plan is grounded in the real code. Working and main are both graph_scopes; claims, flows, components and edges attach through graph_memberships rows tied to a memory_commit, and readGraph decides which claims are live by walking supersedes edges across the union of main and working (activeSubjectKeys).

That surfaces the one thing I want to confirm before coding. A working claim usually supersedes an older main claim through a supersedes edge, so promote has to move that edge along with the claim, or clearing working would bring the stale main claim back to life. My plan is to move every working membership (claims plus their edges) under one new main memory_commit, then empty working the way forget already drops memberships. Does emptying working match what you want, or would you rather keep a tombstone commit on it?

---

Update: implemented in #109, with a before demo here and an after demo on the PR. It moves the working memberships (claims and their supersedes edges together) into main under one commit, then clears working. I went with emptying working rather than a tombstone commit, and can switch if you prefer.

[burrows99]

Quick before demo of the gap this fixes:

repro.mp4