A1: Shared team memory via git-native sync (.greplica/ directory, greplica pull / push)

[Rontu22]

This discussion thread corresponds to item A1 in the roadmap tracking issue #1. It exists as the working example of the triage protocol described there: an item a maintainer marks as genuine/in-scope gets a thread like this one for design debate before any child issue or implementation work is created.

Context (from the tracker)

All Greplica memory lives in a per-user SQLite database under greplicaHome() (libs/config/greplica-home.ts). The value of the product currently ends at the machine boundary: an engineer who resolves a subtle constraint builds memory that no teammate's agent will ever see. For a team, the core value proposition is the opposite: the organization's agents get smarter because any one agent learned something.

Proposal under discussion

A repo-committed .greplica/ directory holding the canonical exported graph, with two new commands:

• greplica push: export the local main-scope graph into .greplica/ using the existing deterministic folder export (libs/knowledge-graph/folder-export.ts).
• greplica pull: import .greplica/ content and three-way merge memory commits into the local SQLite replica, using memory_commits.parent_memory_commit_id as merge ancestry.

Memory then travels with the repository, works air-gapped, is code-reviewable like code (memory changes appear as diffs in PRs), and requires no new infrastructure.

Decision points for this thread

1. On-disk format. Is the current folder-export format stable and merge-friendly enough to serve as the canonical shared representation (one file per object, deterministic ordering), or does it need a redesign for diff readability first?
2. Merge semantics. Proposal is conservative for v1: concurrent edits to the same object surface as a conflict file for human resolution. Is that acceptable, or is last-writer-wins with provenance (tracker item A3) preferable?
3. Scope of sync. Main scope only, or should working-scope memory ever be pushable? (Interaction with upstream issue Feat: Add command to promote working memory to main scope (greplica graph promote) Autoloops/greplica#22, promote-to-main.)
4. Id collisions. Object ids are human-readable slugs; two engineers can independently create claim.sync_auth_mode_startup with different text. Detection and resolution strategy needed (relates to tracker item A6, contradiction detection).
5. Repo bloat and history. Should .greplica/ be committed to the default branch, a dedicated branch, or supported in both modes? What is the expected growth rate for an active team?
6. Relationship to A2. Does the git-native format become the wire format for a later sync service, or are they allowed to diverge?

Open questions

• Should greplica pull run automatically on install/session start when .greplica/ is present, so teammates get shared memory with zero commands?
• How do embeddings behave across machines with different embedding providers configured? (Likely answer: embeddings are local derived state and are never synced; each machine re-embeds. That should be stated explicitly in the design.)

Links

• Tracking issue and full proposal text: Tracking: product roadmap proposals — enterprise capabilities, developer experience features, and unfiled defects #1 (item A1)
• Dependent items: A3 (provenance), A17 (import), A2 (sync service)